> ## Documentation Index > Fetch the complete documentation index at: https://docs.trophy.so/llms.txt > Use this file to discover all available pages before exploring further. # Send a metric change event > Increment or decrement the value of a metric for a user. ## OpenAPI ````yaml https://api.trophy.so/v1/openapi post /metrics/{key}/event openapi: 3.1.0 info: title: Trophy version: 1.19.0 servers: - x-fern-server-name: Application API url: https://api.trophy.so/v1 description: Application API security: [] paths: /metrics/{key}/event: servers: - url: https://api.trophy.so/v1 description: Application API parameters: - $ref: '#/components/parameters/TenantId' post: tags: - Metrics summary: Send a metric change event description: Increment or decrement the value of a metric for a user. operationId: metrics_event parameters: - name: key in: path description: Unique reference of the metric as set when created. required: true schema: type: string example: words-written - name: Idempotency-Key in: header description: The idempotency key for the event. required: false schema: type: string example: e4296e4b-8493-4bd1-9c30-5a1a9ac4d78f requestBody: required: true content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/UpsertedUser' description: The user that triggered the event. value: type: number format: double description: >- The value to add to the user's current total for the given metric. example: 750 attributes: type: object additionalProperties: type: string description: >- Event attributes as key-value pairs. Keys must match existing event attributes set up in the Trophy dashboard. example: category: writing source: mobile-app required: - user - value examples: Successful operation: value: user: email: user@example.com tz: Europe/London id: '18' attributes: department: engineering role: developer value: 750 attributes: category: writing source: mobile-app responses: '201': description: Created event content: application/json: schema: $ref: '#/components/schemas/EventResponse' examples: Successful operation: value: 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 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '422': description: Unprocessible Entity content: application/json: schema: $ref: '#/components/schemas/ErrorBody' security: - ApiKeyAuth: [] x-codeSamples: - lang: javascript source: | 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' } } ); - lang: python source: | from trophy import TrophyApi client = TrophyApi(api_key='YOUR_API_KEY') user = UpsertedUser( id="123", email="user@example.com", tz="Europe/London", subscribedToEmails=True, attributes={ "department": "engineering", "role": "developer" } ) response = client.metrics.event( "words-written", user=user, value=750, attributes={ "category": "writing", "source": "mobile-app" }) - lang: go source: | import ( "context" api "github.com/trophyso/trophy-go" trophyclient "github.com/trophyso/trophy-go/client" "github.com/trophyso/trophy-go/option" ) client := trophyclient.NewClient( option.WithApiKey("YOUR_API_KEY"), ) response, err := client.Metrics.Event( context.TODO(), "words-written", &api.MetricsEventRequest{ User: &api.UpsertedUser{Id: "user-id"}, Value: 750, Attributes: map[string]string{ "category": "writing", "source": "mobile-app", }, }, ) components: parameters: TenantId: name: Tenant-ID in: header description: >- 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. required: false schema: type: string example: customer_12345 schemas: UpsertedUser: title: Upserted User type: object description: An object with editable user fields. allOf: - $ref: '#/components/schemas/UpdatedUser' - type: object properties: id: type: string description: The ID of the user in your database. Must be a string. example: user-id required: - id EventResponse: title: EventResponse type: object properties: eventId: type: string description: The unique ID of the event. example: 0040fe51-6bce-4b44-b0ad-bddc4e123534 metricId: type: string description: The unique ID of the metric that was updated. example: d01dcbcb-d51e-4c12-b054-dc811dcdc623 total: type: number format: double description: The user's new total progress against the metric. example: 750 achievements: type: array items: $ref: '#/components/schemas/UserAchievementResponse' description: Achievements completed as a result of this event. currentStreak: $ref: '#/components/schemas/MetricEventStreakResponse' description: The user's current streak. points: type: object additionalProperties: $ref: '#/components/schemas/MetricEventPointsResponse' description: >- A map of points systems by key. Only contains points systems that were affected by the event. leaderboards: type: object additionalProperties: $ref: '#/components/schemas/MetricEventLeaderboardResponse' description: >- A map of leaderboards by key. Only contains leaderboards that were affected by the event. idempotencyKey: type: string description: The idempotency key used for the event, if one was provided. idempotentReplayed: type: boolean description: Whether the event was replayed due to idempotency. required: - eventId - metricId - total - achievements - currentStreak - points - leaderboards ErrorBody: title: ErrorBody type: object properties: error: type: string required: - error UpdatedUser: title: Updated User type: object description: An object with editable user fields. properties: email: type: string description: The user's email address. Required if subscribeToEmails is true. example: user@example.com name: type: string description: The name to refer to the user by in emails. example: User tz: type: - string - 'null' description: The user's timezone (used for email scheduling). example: Europe/London deviceTokens: type: - array - 'null' description: The user's device tokens, used for push notifications. items: type: string description: The device token. example: - token1 - token2 subscribeToEmails: type: boolean default: true description: >- Whether the user should receive Trophy-powered emails. If false, Trophy will not store the user's email address. example: true attributes: type: object additionalProperties: type: string description: >- User attributes as key-value pairs. Keys must match existing user attributes set up in the Trophy dashboard. example: department: engineering role: developer UserAchievementResponse: title: UserAchievementResponse type: object allOf: - $ref: '#/components/schemas/AchievementResponse' - type: object properties: achievedAt: type: - string - 'null' format: date-time description: >- The date and time the achievement was completed, in ISO 8601 format. Null if the achievement has not been completed. required: - achievedAt MetricEventStreakResponse: title: Streak Response (Metric Event) type: object description: An object representing the user's streak after sending a metric event. allOf: - $ref: '#/components/schemas/BaseStreakResponse' - type: object properties: extended: type: boolean description: Whether this metric event increased the user's streak length. required: - extended MetricEventPointsResponse: title: MetricEventPointsResponse type: object description: Points system response for metric events and achievement completions. allOf: - $ref: '#/components/schemas/PointsResponse' - type: object properties: total: type: integer description: The user's total points level: description: >- The user's new level, included only when the level changed as a result of this event. oneOf: - $ref: '#/components/schemas/PointsLevel' - type: 'null' added: type: integer description: The points added by this event. example: 10 awards: type: array description: Array of trigger awards that added points. items: $ref: '#/components/schemas/PointsAward' required: - total - added - awards MetricEventLeaderboardResponse: title: MetricEventLeaderboardResponse type: object allOf: - $ref: '#/components/schemas/LeaderboardResponse' - type: object properties: start: type: string format: date description: The start date of the current run of the leaderboard. example: '2025-01-01' end: type: - string - 'null' format: date description: >- The end date of the current run of the leaderboard, or null if the run never ends. example: '2025-12-31' rank: type: - integer - 'null' description: >- The user's rank in the leaderboard, or null if the user is not on the leaderboard. example: 100 previousRank: type: - integer - 'null' description: >- The user's rank in the leaderboard before the event, or null if the user was not on the leaderboard before the event. example: 100 threshold: type: integer description: >- The minimum value required to enter the leaderboard according to its current rankings. example: 25000 breakdownAttributeValue: type: string description: >- Deprecated. For leaderboards with a single breakdown attribute, the value of that attribute for the user. deprecated: true example: USA breakdownAttributeValues: type: array description: >- For leaderboards with breakdown attributes, the user's values for each breakdown attribute. items: type: object properties: key: type: string description: The key of the breakdown attribute. example: country value: type: string description: The user's value for the breakdown attribute. example: USA required: - key - value required: - start - end - threshold - rank - previousRank AchievementResponse: title: AchievementResponse type: object properties: id: type: string description: The unique ID of the achievement. name: type: string description: The name of this achievement. trigger: type: string enum: - metric - streak - api - achievement description: The trigger of the achievement. description: type: - string - 'null' description: The description of this achievement. badgeUrl: type: - string - 'null' description: >- The URL of the badge image for the achievement, if one has been uploaded. key: type: string description: >- The key used to reference this achievement in the API (only applicable if trigger = 'api') streakLength: type: integer description: >- The length of the streak required to complete the achievement (only applicable if trigger = 'streak') achievementIds: type: array items: type: string description: >- The IDs of the prerequisite achievements that must be completed to earn this achievement (only applicable if trigger = 'achievement') metricId: type: string description: >- The ID of the metric associated with this achievement (only applicable if trigger = 'metric') metricValue: type: number format: double description: >- The value of the metric required to complete the achievement (only applicable if trigger = 'metric') metricName: type: string description: >- The name of the metric associated with this achievement (only applicable if trigger = 'metric') userAttributes: type: array description: >- User attribute filters that must be met for this achievement to be completed. items: type: object properties: key: type: string description: The key of the user attribute. example: plan-type value: type: string description: The value of the user attribute. example: premium required: - key - value eventAttribute: type: object description: >- Deprecated. Event attribute filter that must be met for this achievement to be completed. Only present if the achievement has an event filter configured. deprecated: true properties: key: type: string description: The key of the event attribute. example: source value: type: string description: The value of the event attribute. example: mobile-app required: - key - value eventAttributes: type: array description: >- Event attribute filters that must be met for this achievement to be completed. Omitted for non-metric achievements. items: type: object properties: key: type: string description: The key of the event attribute. example: source value: type: string description: The value of the event attribute. example: mobile-app required: - key - value required: - id - name - trigger - description - badgeUrl - userAttributes BaseStreakResponse: title: Base Streak Response type: object properties: length: type: integer description: The length of the user's current streak. frequency: $ref: '#/components/schemas/StreakFrequency' description: The frequency of the streak. started: type: - string - 'null' format: date description: The date the streak started. periodStart: type: - string - 'null' format: date description: The start date of the current streak period. periodEnd: type: - string - 'null' format: date description: The end date of the current streak period. expires: type: - string - 'null' format: date description: >- The date the streak will expire if the user does not increment a metric. freezes: type: integer description: >- The number of available streak freezes. Only present if the organization has enabled streak freezes. maxFreezes: type: integer description: >- The maximum number of streak freezes a user can have. Only present if the organization has enabled streak freezes. freezeAutoEarnInterval: type: integer description: >- The interval at which the user will earn streak freezes, in days. Only present if the organization has enabled streak freeze auto-earn. freezeAutoEarnAmount: type: integer description: >- The amount of streak freezes the user will earn per interval. Only present if the organization has enabled streak freeze auto-earn. required: - length - frequency - started - periodStart - periodEnd - expires PointsResponse: title: PointsResponse type: object description: Base points system fields shared across responses. properties: id: type: string description: The ID of the points system key: type: string description: The key of the points system name: type: string description: The name of the points system description: type: - string - 'null' description: The description of the points system badgeUrl: type: - string - 'null' description: The URL of the badge image for the points system maxPoints: type: - number - 'null' description: >- The maximum number of points a user can be awarded in this points system required: - id - key - name - description - badgeUrl - maxPoints PointsLevel: title: PointsLevel type: object description: A level within a points system. properties: id: type: string description: The ID of the level key: type: string description: The unique key of the level name: type: string description: The name of the level description: type: string description: The description of the level badgeUrl: type: - string - 'null' description: The URL of the badge image for the level points: type: integer description: The points threshold required to reach this level required: - id - key - name - description - badgeUrl - points PointsAward: title: PointsAward type: object properties: id: type: string description: The ID of the trigger award awarded: type: integer description: The points awarded by this trigger date: type: string description: The date these points were awarded, in ISO 8601 format. total: type: integer description: The user's total points after this award occurred. trigger: $ref: '#/components/schemas/PointsTrigger' boosts: type: array description: Array of points boosts that applied to this award. items: $ref: '#/components/schemas/PointsBoost' LeaderboardResponse: title: LeaderboardResponse type: object description: A leaderboard with its configuration details. properties: id: type: string description: The unique ID of the leaderboard. example: 5100fe51-6bce-6j44-b0hs-bddc4e123682 name: type: string description: The user-facing name of the leaderboard. example: Weekly Word Count Challenge key: type: string description: The unique key used to reference the leaderboard in APIs. example: weekly-words rankBy: type: string enum: - points - streak - metric description: What the leaderboard ranks by. example: metric breakdownAttribute: type: - string - 'null' description: >- Deprecated. The key of the attribute to break down this leaderboard by. deprecated: true example: country breakdownAttributes: type: array description: The user attribute keys that this leaderboard is broken down by. items: type: string description: The key of a user attribute in this leaderboard breakdown. example: country metricKey: type: string description: The key of the metric to rank by, if rankBy is 'metric'. example: words-written metricName: type: string description: The name of the metric to rank by, if rankBy is 'metric'. example: Words Written pointsSystemKey: type: string description: The key of the points system to rank by, if rankBy is 'points'. example: xp-system pointsSystemName: type: string description: The name of the points system to rank by, if rankBy is 'points'. example: Experience Points description: type: - string - 'null' description: The user-facing description of the leaderboard. example: Compete weekly to see who writes the most words start: type: string format: date description: The start date of the leaderboard in YYYY-MM-DD format. example: '2025-01-01' end: type: - string - 'null' format: date description: >- The end date of the leaderboard in YYYY-MM-DD format, or null if it runs forever. example: '2025-12-31' startTime: type: - string - 'null' pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: >- When set, ranking only counts activity at or after this time of day in the user's timezone (HH:mm format). example: '09:00' endTime: type: - string - 'null' pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: >- When set, ranking only counts activity before this time of day in the user's timezone (HH:mm format). example: '17:00' maxParticipants: type: - integer - 'null' description: The maximum number of participants in the leaderboard. example: 100 runUnit: type: - string - 'null' enum: - day - month - year - null description: >- The repetition type for recurring leaderboards, or null for one-time leaderboards. example: day runInterval: type: - integer - 'null' description: >- The interval between repetitions, relative to the start date and repetition type. Null for one-time leaderboards. example: 7 required: - id - name - key - status - description - rankBy - breakdownAttribute - breakdownAttributes - start - end - startTime - endTime - maxParticipants - runUnit - runInterval StreakFrequency: title: StreakFrequency type: string enum: - daily - weekly - monthly PointsTrigger: title: PointsTrigger type: object properties: id: type: string description: The ID of the trigger type: type: string description: The type of trigger enum: - metric - achievement - streak - time - user_creation points: type: integer description: The points awarded by this trigger. status: type: string enum: - active - inactive - archived description: The status of the trigger. achievementId: type: string description: >- The unique ID of the achievement associated with this trigger, if the trigger is an achievement. metricId: type: string description: >- The unique ID of the metric associated with this trigger, if the trigger is a metric. metricName: type: string description: If the trigger has type 'metric', the name of the metric metricThreshold: type: integer description: >- If the trigger has type 'metric', the threshold of the metric that triggers the points streakLengthThreshold: type: integer description: >- If the trigger has type 'streak', the threshold of the streak that triggers the points achievementName: type: string description: If the trigger has type 'achievement', the name of the achievement timeUnit: type: string enum: - hour - day description: >- If the trigger has type 'time', the unit of time after which to award points timeInterval: type: integer description: >- If the trigger has type 'time', the numer of units of timeUnit after which to award points userAttributes: type: array description: >- User attribute filters that must be met for this trigger to award points. Empty when the trigger has no user attribute filters configured. items: type: object properties: key: type: string description: The key of the user attribute. example: plan-type value: type: string description: The required value of the user attribute. example: premium required: - key - value eventAttribute: type: object description: >- Deprecated. Event attribute filter that must be met for this trigger to award points. Only present if the trigger has an event filter configured. deprecated: true properties: key: type: string description: The key of the event attribute. example: source value: type: string description: The required value of the event attribute. example: mobile-app required: - key - value eventAttributes: type: array description: >- If the trigger has type 'metric', the event attributes that must match for the trigger to award points. Empty when the trigger is metric-based and has no event attribute filters. Omitted for non-metric triggers. items: type: object properties: key: type: string description: The key of the event attribute. example: source value: type: string description: The required value of the event attribute. example: mobile-app required: - key - value created: type: string format: date-time description: The date and time the trigger was created, in ISO 8601 format. updated: type: string format: date-time description: The date and time the trigger was last updated, in ISO 8601 format. required: - id - type - points - status - userAttributes - created - updated PointsBoost: title: PointsBoost type: object properties: id: type: string description: The ID of the points boost name: type: string description: The name of the points boost status: type: string enum: - active - scheduled - finished description: The status of the points boost start: type: string description: The start date of the points boost end: type: - string - 'null' description: The end date of the points boost multiplier: type: number description: The multiplier of the points boost rounding: type: string enum: - down - up - nearest description: The rounding method of the points boost required: - id - name - status - start - end - multiplier - rounding securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````