POST
/
metrics
/
{key}
/
event
JavaScript
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.metrics.event(
  "words-written",
  {
    user: {
      id: 'user-id',
      email: 'user@example.com',
      tz: 'Europe/London',
      subscribedToEmails: true,
      attributes: {
        department: 'engineering',
        role: 'developer'
      }
    },
    value: 750,
    attributes: {
      category: 'writing',
      source: 'mobile-app'
    }
  }
);
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  "achievements": [
    {
      "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "trigger": "metric",
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "metricName": "words written",
      "metricValue": 500,
      "name": "500 words written",
      "description": "Write 500 words in the app.",
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  },
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "total": 10,
      "added": 10,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 10,
          "date": "2021-01-01T00:00:00Z",
          "total": 10,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "words written",
            "metricThreshold": 100,
            "points": 10
          }
        }
      ]
    }
  },
  "leaderboards": {
    "all-time": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
      "key": "all-time",
      "name": "All-Time Leaderboard",
      "description": null,
      "rankBy": "metric",
      "runUnit": null,
      "runInterval": 0,
      "maxParticipants": 100,
      "metricName": "words written",
      "metricKey": "words-written",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "previousRank": null,
      "rank": 100
    }
  }
}

Authorizations

X-API-KEY
string
header
required

Headers

Idempotency-Key
string

The idempotency key for the event.

Path Parameters

key
string
required

Unique reference of the metric as set when created.

Body

application/json
user
object
required

The user that triggered the event. An object with editable user fields.

value
number
required

The value to add to the user's current total for the given metric.

Example:

750

attributes
object

Event attributes as key-value pairs. Keys must match existing event attributes set up in the Trophy dashboard.

Example:
{
"category": "writing",
"source": "mobile-app"
}

Response

Created event

eventId
string
required

The unique ID of the event.

Example:

"0040fe51-6bce-4b44-b0ad-bddc4e123534"

metricId
string
required

The unique ID of the metric that was updated.

Example:

"d01dcbcb-d51e-4c12-b054-dc811dcdc623"

total
number
required

The user's new total progress against the metric.

Example:

750

achievements
CompletedAchievementResponse · object[]
required

Achievements completed as a result of this event.

currentStreak
object
required

The user's current streak.

points
object
required

A map of points systems by key.

leaderboards
object
required

A map of leaderboards by key.

idempotencyKey
string

The idempotency key used for the event, if one was provided.

idempotentReplayed
boolean

Whether the event was replayed due to idempotency.