Wrapped API

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.

Get API keyAPI reference
SDKs for
NodeJSGoJava.NETPHPPythonRuby

Quickstart

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.

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);

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.

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.

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.

POST/metrics/{key}/eventView docs

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

Path Parameters

keystringrequired

Unique reference of the metric as set when created.

Request Body

userUserrequired

The user that triggered the event (must include id).

valuenumberrequired

The value to add to the user's current total for the given metric.

Response

eventIdstring

Unique identifier for the created event.

totalnumber

The 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/users/{id}/wrappedView docs

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

Path Parameters

idstringrequired

The user's ID in your database.

Query Parameters

yearinteger

Year to get wrapped data for (default: 2026).

Response

userUser

The user's profile data.

activity.daysActivenumber

Total days the user was active during the year.

activity.mostActiveDayobject

The user's most active day with metrics, points, and achievements.

activity.entireYearobject

Full-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 platform to effortlessly build engaging user experiences. Get a team that's 100% focused on engagement.

NodeJS
Go
Java
.NET
PHP
Python
Ruby
Get startedAPI reference
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.

Uptime SLA
99.99%
p95 API Latency
200ms
Monthly API Requests
150M
Users Tracked
1M+

FAQ

Frequently asked questions

Have a different question and can’t find the answer you’re looking for? Send us an email.

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.

Get started

Up and running in minutes

Start

Start building

Integrate in minutes, interpret in hours. No credit card required.

Start for free

Explore

See what's possible

Explore how Trophy can increase user engagement and retention.

Book a call

Compare

Compare plans

Understand the free tier limits and Trophy's usage-based model.

See pricing