---
title: Wrapped API
canonical_url: "https://trophy.so/developers/wrapped"
description: "The wrapped API for consumer apps. Aggregate user activity into personalized year-in-review recaps, ready to render. SDKs for Node.js, Python, Go, Java, PHP, Ruby, and .NET."
---

# The wrapped API for consumer apps

Trophy's year-in-review API aggregates your users' entire year of activity into a shareable wrapped recap automatically. You get back days active, highlights, achievements, and longest streak — all you build is the UI. Start for free, scale to millions of users.

[Full feature documentation](https://docs.trophy.so/api-reference/endpoints/users/get-a-users-wrapped.md)

## Quickstart: track activity and fetch Wrapped

Keep sending metric events throughout the year. When you are ready to render a recap, fetch the user’s aggregated Wrapped summary for that year.

```ts
import { TrophyApiClient } from "@trophyso/node";

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

// 1. Track activity as usual — Wrapped aggregation runs in the background
await trophy.metrics.event("lessons", {
  user: { id: "user-123" },
  value: 1,
});

// 2. Fetch the year-in-review summary when you are ready to render
const wrapped = await trophy.users.wrapped("user-123", {
  year: 2026,
});

console.log("Days active:", wrapped.activity.daysActive);
console.log("Longest streak:", wrapped.activity.entireYear.longestStreak);
console.log("Achievements:", wrapped.activity.entireYear.achievements);
```

## Why use Trophy's wrapped API?

Building a year in review API from scratch means writing aggregation pipelines, computing highlights, and generating personalised annual recaps for your entire user base at once — typically a multi-week engineering project every year.

| Consideration | Trophy | Build in-house | Why it matters |
| --- | --- | --- | --- |
| Integration Time | One API call returns a complete personalized summary for any user. No aggregation code needed. | Build data aggregation pipelines, compute highlights and comparisons, handle incomplete data, and design summary templates. Expect 6-10 weeks. | Year-in-review summaries require aggregating months of historical data into meaningful highlights. Building the pipeline, computing percentiles, and mining the most relevant data points for each user is a project in itself. |
| Reliability | Trophy pre-computes summaries from event data already in the system. No data gaps or missing history. | You must ensure complete data capture for the entire review period. Any gaps in your event pipeline mean missing or inaccurate summaries. | A wrapped summary that shows incorrect totals or missing highlights defeats the purpose. Users will notice if their stats don't match their experience. |
| Scalability | Trophy generates summaries for all users without infrastructure spikes or batch processing bottlenecks. | Generating personalized summaries for your entire user base simultaneously creates massive compute spikes that require careful capacity planning. | Wrapped features typically launch on a single day, creating a thundering-herd problem. All summaries need to be ready at once, and all users access them at once. |
| Ongoing Maintenance | Summaries are generated automatically from your existing metric events. No annual engineering sprint required. | Each year requires updating aggregation queries, adding new highlight types, and re-testing the pipeline — typically a multi-week annual project. | Wrapped features shouldn't be an annual fire drill. If generating summaries requires a dedicated engineering sprint every year, the cost compounds. |
| Feature Development | New summary types, comparison metrics, and presentation options are added every year. | Each new highlight type — top streaks, achievement rarity, peer comparisons — requires new aggregation logic and careful data modeling. Each year requires a new engineering sprint to update the aggregation pipeline. | Users expect wrapped summaries to get better each year. The ability to add new highlight types without re-engineering your aggregation pipeline every year is key. |

## Wrapped endpoints

Use Trophy's wrapped API to fetch a complete user activity summary for any year. Aggregation runs automatically in the background — call the endpoint when you're ready to render.

### `POST /metrics/{key}/event`

Send a metric event to track user activity and power wrapped recaps.

Docs: https://docs.trophy.so/api-reference/endpoints/metrics/send-a-metric-change-event.md

```ts
// Track a user event
await trophy.metrics.event("lessons", {
    user: {
      id: "user-123"
    },
    value: 1
  }
);

// This single event:
// - Records user activity
// - Computes wrapped data
```

### `GET /users/{id}/wrapped`

Get a user's year-in-review wrapped data including activity breakdown, highlights, and comparisons.

Docs: https://docs.trophy.so/api-reference/endpoints/users/get-a-users-wrapped.md

```ts
// Fetch user's wrapped data
const wrapped = await trophy.users.wrapped("user-123", {
  year: 2026
});

// Response:
// { 
//   user: {...},
//   activity: {
//     daysActive: 156, 
//     weeksActive: 42,
//     monthsActive: 7,
//     mostActiveDay: {...},
//     mostActiveWeek: {...},
//     mostActiveMonth: {...},
//     entireYear: { 
//       metrics: {...},
//       points: {...},
//       achievements: [...],
//       leaderboards: {...},
//       longestStreak: {...} 
//     } 
//   } 
// }
```

## Code examples

### wrapped-page.tsx

```ts
// Build a wrapped experience

const wrapped = await trophy.users
  .wrapped(userId, { year: 2026 });

return (
  <WrappedCard
    daysActive={wrapped.activity.daysActive}
    longestStreak={wrapped.activity.entireYear.longestStreak}
    achievements={wrapped.activity.entireYear.achievements}
  />
);
```

## FAQ

### What is a Wrapped experience?

A wrapped feature is a personalised year-in-review summary for each user — similar to Spotify Wrapped. It surfaces their activity, achievements, streaks, and milestones across the year in a format designed to be shared. Trophy generates the underlying data automatically from the metric events you send throughout the year.

### How do I build a Spotify Wrapped-style feature for my app?

Trophy's year in review API does the aggregation work automatically. Call the wrapped endpoint with a user ID and year, and you get back a complete annual user recap — days active, most active periods, achievements earned, longest streak, and more. You focus entirely on the UI.

### What data is included in the Wrapped response?

The user activity summary includes total days, weeks, and months active; the most active day, week, and month with detailed metric breakdowns; full-year totals for metrics, points, and achievements; leaderboard standings; and longest streak data. Everything needed to build a compelling annual recap.

### Do I need to do anything special to enable Wrapped?

No. As long as you're sending metric events to Trophy throughout the year, the data needed to power an app wrapped feature is accumulated automatically. Call the API when you're ready to build your year-in-review experience — no backfilling or additional setup needed.

### Can users share their Wrapped recap?

Trophy provides the data — you design the shareable wrapped experience. Most teams build a dedicated page or card that users can screenshot or share via link. The API returns all the stats needed to create compelling, personalised content: streaks, achievements, most active periods, and full-year totals.

### Can I build Wrapped experiences in React, React Native, or mobile apps?

Yes. Building wrapped experiences with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) to fetch the annual recap from your backend. The API returns activity summaries, highlights, and stats that you can render in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework.