Wrapped API
The API for Wrapped 2026
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.
SDKs for
Endpoints
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.
Send a metric event to track user activity and power wrapped recaps.
Path Parameters
keystringrequiredUnique reference of the metric as set when created.
Request Body
userUserrequiredThe user that triggered the event (must include id).
valuenumberrequiredThe value to add to the user's current total for the given metric.
Response
eventIdstringUnique identifier for the created event.
totalnumberThe user's new total for this metric.
Example
import { TrophyApiClient } from '@trophyso/node';
const trophy = new TrophyApiClient({
apiKey: 'YOUR_API_KEY'
});
// 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 a user's year-in-review wrapped data including activity breakdown, highlights, and comparisons.
Path Parameters
idstringrequiredThe user's ID in your database.
Query Parameters
yearintegerYear to get wrapped data for (default: 2026).
Response
userUserThe user's profile data.
activity.daysActivenumberTotal days the user was active during the year.
activity.mostActiveDayobjectThe user's most active day with metrics, points, and achievements.
activity.entireYearobjectFull-year summary with metrics, points, achievements, and longest streak.
Example
import { TrophyApiClient } from '@trophyso/node';
const trophy = new TrophyApiClient({
apiKey: 'YOUR_API_KEY'
});
// 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: {...}
// }
// }
// }Lightning-Fast Integration
Simple APIs you'll Love
Use our pre-built gamification API to effortlessly build engaging user experiences. Get a team that's 100% focused on engagement.
- Type-safe SDKs.
- We spend time worrying about abstractions and let you focus on what matters: building a great experience for your users.
- Intuitive documentation.
- Documentation built by developers for developers. Get started in minutes, not hours.
- Effortless debugging.
- Get to the root of the issue fast with detailed event logs and error messages.
// 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}
/>
);Built for production workloads
Reliable infrastructure designed for performance at scale.
- Historical Uptime
- 99.99%
- Avg Response Time
- <50ms
- Integration Time
- < 1 hour
- Users Tracked
- 1M+
Buy vs. Build
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.
| Key Considerations | Build | Why does it matter? | |
|---|---|---|---|
| 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. |
Integration Time
One API call returns a complete personalized summary for any user. No aggregation code needed.
Build
Build data aggregation pipelines, compute highlights and comparisons, handle incomplete data, and design summary templates. Expect 6-10 weeks.
Why does it matter?
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.
Build
You must ensure complete data capture for the entire review period. Any gaps in your event pipeline mean missing or inaccurate summaries.
Why does it matter?
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.
Build
Generating personalized summaries for your entire user base simultaneously creates massive compute spikes that require careful capacity planning.
Why does it matter?
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.
Build
Each year requires updating aggregation queries, adding new highlight types, and re-testing the pipeline — typically a multi-week annual project.
Why does it matter?
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.
Build
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.
Why does it matter?
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.
FAQ
Frequently asked questions
Have a different question and can’t find the answer you’re looking for?
- 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.
Gamification infrastructure that retains users
Boost retention and customer lifetime value. Try for free up to 100 MAUs.
