Skip to main content
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,
      "level": {
        "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
        "key": "bronze",
        "name": "Bronze",
        "description": "Starting level",
        "badgeUrl": null,
        "points": 0
      },
      "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": null,
      "maxParticipants": 100,
      "breakdownAttribute": null,
      "metricName": "words written",
      "metricKey": "words-written",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "previousRank": null,
      "rank": 100
    }
  }
}
Rate Limits

Authorizations

​
X-API-KEY
string
header
required

Headers

​
Idempotency-Key
string

The idempotency key for the event.

​
Tenant-ID
string

The tenant identifier for multi-tenant organisations. Required when the organisation has multi-tenancy enabled. The value should be your internal ID for the tenant. Ignored for single-tenant organisations.

Path Parameters

​
key
string
required

Unique reference of the metric as set when created.

Body

application/json
​
user
Upserted User · object
required

The user that triggered the event.

​
value
number<double>
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<double>
required

The user's new total progress against the metric.

Example:

750

​
achievements
UserAchievementResponse · object[]
required

Achievements completed as a result of this event.

​
currentStreak
Streak Response (Metric Event) · object
required

The user's current streak.

​
points
object
required

A map of points systems by key. Only contains points systems that were affected by the event.

​
leaderboards
object
required

A map of leaderboards by key. Only contains leaderboards that were affected by the event.

​
idempotencyKey
string

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

​
idempotentReplayed
boolean

Whether the event was replayed due to idempotency.