> ## Documentation Index > Fetch the complete documentation index at: https://trophy-ci-i18n-auto-translations.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get a user's wrapped data > Get a user's year-in-review wrapped data. ## OpenAPI ````yaml https://api.trophy.so/v1/openapi get /users/{id}/wrapped 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: /users/{id}/wrapped: servers: - url: https://api.trophy.so/v1 description: Application API parameters: - $ref: '#/components/parameters/TenantId' get: tags: - Users summary: Get a user's wrapped data description: Get a user's year-in-review wrapped data. operationId: users_wrapped parameters: - name: id in: path description: The user's ID in your database. required: true schema: type: string example: user-123 - name: year in: query description: >- The year to get wrapped data for. Defaults to the current year. Must be an integer between 1 and the current year. required: false schema: type: integer minimum: 1 example: 2024 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WrappedResponse' examples: Successful operation: value: user: id: user-123 email: user@example.com name: John Doe tz: America/New_York subscribeToEmails: true created: '2024-01-15T10:30:00Z' updated: '2024-06-20T14:45:00Z' control: false attributes: plan-type: premium region: us-east activity: daysActive: 156 weeksActive: 42 monthsActive: 11 mostActiveDay: date: '2024-03-15' metrics: words-written: name: Words Written units: words currentTotal: 15000 changeThisPeriod: 2500 percentChange: 20 byAttribute: {} points: xp-system: name: Experience Points description: Points earned through activity currentTotal: 5000 changeThisPeriod: 500 percentChange: 11.1 achievements: - id: 5100fe51-6bce-6j44-b0hs-bddc4e123682 name: 500 Words Written trigger: metric description: Write 500 words in a single day badgeUrl: https://example.com/badge.png key: 500-words metricId: metric-123 metricValue: 500 metricName: Words Written achievedAt: '2024-03-15T14:30:00Z' completions: 150 rarity: 15 leaderboards: weekly-words: id: leaderboard-123 name: Weekly Word Count key: weekly-words rankBy: metric metricKey: words-written metricName: Words Written description: Weekly writing competition start: '2024-03-11' end: '2024-03-17' maxParticipants: 100 runUnit: day runInterval: 7 rank: 3 value: 2500 mostActiveWeek: start: '2024-03-11' end: '2024-03-17' metrics: words-written: name: Words Written units: words currentTotal: 15000 changeThisPeriod: 8500 percentChange: 130 percentileThisPeriod: 95 byAttribute: {} points: xp-system: name: Experience Points description: Points earned through activity currentTotal: 5000 changeThisPeriod: 1200 percentChange: 31.5 percentileThisPeriod: 88 achievements: [] leaderboards: {} mostActiveMonth: month: 2 metrics: words-written: name: Words Written units: words currentTotal: 15000 changeThisPeriod: 12000 percentChange: 400 percentileThisPeriod: 92 byAttribute: {} points: xp-system: name: Experience Points description: Points earned through activity currentTotal: 5000 changeThisPeriod: 2000 percentChange: 66.6 percentileThisPeriod: 85 achievements: [] leaderboards: {} entireYear: metrics: words-written: name: Words Written units: words currentTotal: 150000 changeThisPeriod: 150000 percentChange: 100 percentileThisPeriod: 78 byAttribute: {} points: xp-system: name: Experience Points description: Points earned through activity currentTotal: 25000 changeThisPeriod: 25000 percentChange: 100 percentileThisPeriod: 82 achievements: - id: 5100fe51-6bce-6j44-b0hs-bddc4e123682 name: 500 Words Written trigger: metric description: Write 500 words in a single day badgeUrl: https://example.com/badge.png key: 500-words metricId: metric-123 metricValue: 500 metricName: Words Written achievedAt: '2024-03-15T14:30:00Z' completions: 150 rarity: 15 leaderboards: {} longestStreak: length: 45 frequency: daily periodStart: '2024-02-01' periodEnd: '2024-03-17' started: '2024-02-01' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '404': description: User not found 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.users.wrapped("user-123", { year: 2024 }); - lang: python source: | from trophy import TrophyApi client = TrophyApi(api_key='YOUR_API_KEY') response = client.users.wrapped(id="user-123", year=2024) - 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.Users.Wrapped( context.TODO(), "user-123", &api.UsersWrappedRequest{Year: api.Int(2024)}, ) 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: WrappedResponse: title: WrappedResponse type: object description: >- A user's year-in-review wrapped data including activity summaries, metrics, points, achievements, streaks, and leaderboard rankings. properties: user: $ref: '#/components/schemas/User' description: The user's profile information. activity: $ref: '#/components/schemas/WrappedActivity' description: The user's activity data for the wrapped year. required: - user - activity ErrorBody: title: ErrorBody type: object properties: error: type: string required: - error User: title: User type: object description: A user of your application. properties: id: type: string description: The ID of the user in your database. Must be a string. example: user-id email: type: - string - 'null' description: The user's email address. example: user@example.com name: type: - string - 'null' description: The name of the user. example: John Doe tz: type: - string - 'null' description: The user's timezone. example: Europe/London deviceTokens: type: - array - 'null' description: The user's device tokens. items: type: string description: The device token. example: - token1 - token2 subscribeToEmails: type: boolean description: Whether the user is opted into receiving Trophy-powered emails. 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 control: type: boolean description: >- Whether the user is in the control group, meaning they do not receive emails or other communications from Trophy. example: false created: type: string format: date-time description: The date and time the user was created, in ISO 8601 format. example: '2021-01-01T00:00:00Z' updated: type: string format: date-time description: The date and time the user was last updated, in ISO 8601 format. example: '2021-01-01T00:00:00Z' required: - id - email - name - tz - subscribeToEmails - attributes - control - created - updated WrappedActivity: title: WrappedActivity type: object description: The user's activity summary for the wrapped year. properties: daysActive: type: integer description: The number of days the user was active during the year. example: 156 weeksActive: type: integer description: The number of weeks the user was active during the year. example: 42 monthsActive: type: integer description: The number of months the user was active during the year. example: 11 mostActiveDay: $ref: '#/components/schemas/WrappedMostActiveDay' description: Data about the user's most active day. mostActiveWeek: $ref: '#/components/schemas/WrappedMostActiveWeek' description: Data about the user's most active week. mostActiveMonth: $ref: '#/components/schemas/WrappedMostActiveMonth' description: Data about the user's most active month. entireYear: $ref: '#/components/schemas/WrappedEntireYear' description: Data about the user's activity for the entire year. required: - daysActive - weeksActive - monthsActive - mostActiveDay - mostActiveWeek - mostActiveMonth - entireYear WrappedMostActiveDay: title: WrappedMostActiveDay type: object description: The user's most active day during the year. allOf: - $ref: '#/components/schemas/WrappedActivityPeriod' - type: object properties: date: type: string format: date description: The date of the most active day in YYYY-MM-DD format. example: '2024-03-15' required: - date WrappedMostActiveWeek: title: WrappedMostActiveWeek type: object description: The user's most active week during the year. allOf: - $ref: '#/components/schemas/WrappedActivityPeriod' - type: object properties: start: type: string format: date description: The start date of the most active week in YYYY-MM-DD format. example: '2024-03-11' end: type: string format: date description: The end date of the most active week in YYYY-MM-DD format. example: '2024-03-17' required: - start - end WrappedMostActiveMonth: title: WrappedMostActiveMonth type: object description: The user's most active month during the year. allOf: - $ref: '#/components/schemas/WrappedActivityPeriod' - type: object properties: month: type: integer minimum: 0 maximum: 11 description: The month number (0-11, where 0 is January). example: 2 required: - month WrappedEntireYear: title: WrappedEntireYear type: object description: The user's activity data for the entire year. allOf: - $ref: '#/components/schemas/WrappedActivityPeriod' - type: object properties: longestStreak: $ref: '#/components/schemas/WrappedStreak' description: The user's longest streak during the year. required: - longestStreak WrappedActivityPeriod: title: WrappedActivityPeriod type: object description: Activity data for a specific period (day, week, month, or year). properties: metrics: type: object additionalProperties: $ref: '#/components/schemas/WrappedMetric' description: The user's metrics during this period, keyed by metric key. points: type: object additionalProperties: $ref: '#/components/schemas/WrappedPoints' description: The user's points during this period, keyed by points system key. achievements: type: array items: $ref: '#/components/schemas/UserAchievementResponse' description: Achievements completed during this period. leaderboards: type: object additionalProperties: $ref: '#/components/schemas/UserLeaderboardResponse' description: >- The user's best leaderboard rankings during this period, keyed by leaderboard key. required: - metrics - points - achievements - leaderboards WrappedStreak: title: WrappedStreak type: object description: The user's longest streak during the wrapped period. properties: length: type: integer description: The length of the streak. example: 45 frequency: $ref: '#/components/schemas/StreakFrequency' description: The frequency of the streak. periodStart: type: - string - 'null' format: date description: The start date of the streak period. example: '2024-02-01' periodEnd: type: - string - 'null' format: date description: The end date of the streak period. example: '2024-03-17' started: type: - string - 'null' format: date description: The date the streak started. example: '2024-02-01' required: - length - frequency - periodStart - periodEnd - started WrappedMetric: title: WrappedMetric type: object description: A user's metric data for a wrapped period. properties: name: type: string description: The name of the metric. example: Words Written units: type: - string - 'null' description: The units of the metric. example: words currentTotal: type: number description: The user's current total for the metric. example: 15000 changeThisPeriod: type: number description: The change in the metric value during the period. example: 2500 percentChange: type: number description: The percentage change in the metric value during the period. example: 20 percentileThisPeriod: type: number description: >- The user's percentile rank for this metric during the period. Only included for weekly, monthly, and yearly aggregation periods. example: 85 byAttribute: type: object additionalProperties: type: object additionalProperties: type: object properties: name: type: string description: The name of the metric. units: type: - string - 'null' description: The units of the metric. currentTotal: type: number description: The current total for this attribute value. changeThisPeriod: type: number description: The change during the period for this attribute value. percentChange: type: number description: The percentage change for this attribute value. percentileThisPeriod: type: number description: >- The user's percentile rank for this attribute value during the period. description: Metric data broken down by attribute key and value. required: - name - currentTotal - changeThisPeriod - percentChange - byAttribute WrappedPoints: title: WrappedPoints type: object description: A user's points data for a wrapped period. properties: name: type: string description: The name of the points system. example: Experience Points description: type: - string - 'null' description: The description of the points system. example: Points earned through activity currentTotal: type: number description: The user's current total points. example: 5000 changeThisPeriod: type: number description: The change in points during the period. example: 500 percentChange: type: number description: The percentage change in points during the period. example: 11.1 percentileThisPeriod: type: number description: >- The user's percentile rank for this points system during the period. Only included for weekly, monthly, and yearly aggregation periods. example: 88 required: - name - currentTotal - changeThisPeriod - percentChange 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 UserLeaderboardResponse: title: UserLeaderboardResponse type: object description: >- A user's data for a specific leaderboard including rank, value, and history. allOf: - $ref: '#/components/schemas/LeaderboardResponse' - type: object properties: rank: type: - integer - 'null' description: >- The user's current rank in this leaderboard. Null if the user is not on the leaderboard. example: 2 value: type: - integer - 'null' description: >- The user's current value in this leaderboard. Null if the user is not on the leaderboard. example: 4500 required: - rank - value StreakFrequency: title: StreakFrequency type: string enum: - daily - weekly - monthly 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 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````