---
title: Milestones API
canonical_url: "https://trophy.so/developers/milestones"
description: "The milestones and achievements API for consumer web and mobile apps. Award milestones automatically from in-app events, streaks, or custom API triggers. SDKs for Node.js, Python, Go, Java, PHP, Ruby, and .NET."
---

# The milestones API for consumer web and mobile apps

Add milestones to your consumer app in under an hour. Trophy handles trigger evaluation, badge hosting, progress tracking and rarity calculations so you can focus on the user experience. Scales to millions of users.

[Full feature documentation](https://docs.trophy.so/features/achievements.md)

## Quickstart: three-call integration

Configure your milestones in the Trophy dashboard first, then use this code to track user progress, check unlocks, and mark completions. The full lifecycle takes three calls.

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

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

// 1. Track a metric event (e.g., user completed a lesson)
const eventResponse = await trophy.metrics.event("lessons", {
  user: { id: "user-123" },
  value: 1,
});

console.log("Event ID:", eventResponse.eventId);
console.log("Lifetime total:", eventResponse.total);

// 2. Check if any achievements unlocked from this event
if (eventResponse.achievements.length > 0) {
  for (const achievement of eventResponse.achievements) {
    console.log("Unlocked:", achievement.name, "| Badge:", achievement.badgeUrl);
  }
}

// 3. Fetch all achievements for a user (for profile display, history, etc.)
const userAchievements = await trophy.users.achievements("user-123");

for (const a of userAchievements) {
  console.log(a.name, "| Achieved:", a.achievedAt, "| Rarity:", a.rarity);
}

// 4. Mark an event-triggered achievement complete (e.g., finished onboarding)
const completion = await trophy.achievements.complete("finish-onboarding", {
  user: { id: "user-123" },
});

console.log("Completion ID:", completion.completionId);
console.log("Points awarded:", completion.points);
```

## Why use Trophy's milestones and achievements API?

A milestones API looks simple on the surface — store a completion flag, return a URL. The trigger evaluation, deduplication, and progress tracking underneath are where the complexity compounds.

| Consideration | Trophy | Build in-house | Why it matters |
| --- | --- | --- | --- |
| Integration Time | Configure milestones in the dashboard, integrate with one API call. Live in under an hour. | Design trigger evaluation engine, badge hosting mechanism, progress tracking, and rarity calculations. Expect 3-4 weeks for initial setup, with ongoing maintenance required for new milestones and updates. | Milestone systems look simple on the surface but require complex trigger logic for progression thresholds, streak lengths and compound conditions that grows with every new milestone added. |
| Reliability | Exactly-once milestone completion with built-in deduplication. | You must guarantee milestones are awarded exactly once — not zero times, not twice — even under concurrent events and race conditions. | Double-awarding a milestone erodes user trust and creates support tickets. Missing one frustrates users who earned it and creates a bad experience. Both are hard to debug retroactively. |
| Scalability | Trophy evaluates milestone triggers millions of times a day in real time without performance degradation. | As you add more milestones and users, trigger evaluation becomes a combinatorial problem. Naive implementations degrade quickly and become hard to change at scale. | Every metric event needs to be checked against every relevant milestone which requires careful indexing and query optimization at scale. |
| Ongoing Maintenance | Add and update milestones from the dashboard. No code changes or deployments needed. Non-technical users can do this themselves. | Each new milestone requires code changes for trigger logic, database migrations for new thresholds, and testing across edge cases. Each update requires a deploy, creating a bottleneck between product and engineering. | Product teams want to iterate on milestones frequently. If every change requires a deploy, you create a bottleneck between product and engineering. |
| Feature Development | Badge hosting, rarity calculations, progress tracking, and new trigger types ship regularly. | Features like rarity percentages, progress bars, and compound triggers each require significant development and ongoing maintenance. | Users expect polished milestone experiences — progress indicators, rarity badges, shareable completions. Building each of these in-house adds up. |

## Objective types

Trophy milestones can trigger in three ways. Configure the objective type and threshold in the dashboard, then send the matching API call.

| Objective type | What triggers it | Example | How you send it |
| --- | --- | --- | --- |
| Metric-based | User's lifetime metric total crosses the threshold you set | Wrote 10,000 words | trophy.metrics.event() with the metric key and value |
| Streak-based | User hits a streak milestone | 7-day streak | trophy.metrics.event() on the streak metric (Trophy tracks consecutive days) |
| Event-based | Your code calls the complete endpoint directly | Completed onboarding | trophy.achievements.complete() with the milestone key |

### Metric-based

Track incremental progress toward a threshold. Trophy sums events and unlocks the milestone when the total crosses the configured value.

```javascript
await trophy.metrics.event("words-written", {
  user: { id: "user-123" },
  value: 500,
});
```

### Streak-based

Track daily activity on a streak metric. Trophy handles the consecutive-day logic and unlocks milestones at configured streak lengths (7 days, 30 days, etc.).

```javascript
await trophy.metrics.event("daily-practice", {
  user: { id: "user-123" },
  value: 1,
});
```

### Event-based

Trigger a milestone directly when a user completes a one-time action.

```javascript
await trophy.achievements.complete("finish-onboarding", {
  user: { id: "user-123" },
});
```

## Milestone endpoints

Use Trophy's milestone tracking API to unlock milestones automatically from metric events, streak lengths, or direct API calls. Progress is evaluated in real time with every event you send.

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

Send a metric event to track user activity and power milestones.

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
// - Evaluates achievement triggers
// - Returns new unlocked achievements
```

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

Get a user's milestones. By default returns only completed milestones.

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

```ts
// Fetch all achievements for a user
const achievements = await trophy.users
  .achievements("user-123");

// Response:
// [
//   { 
//     key: "completed-onboarding", 
//     name: "Completed Onboarding",
//     trigger: "api",
//     achievedAt: "2021-01-01T00:00:00Z",
//     badgeUrl: "https://...", 
//     rarity: 50 
//   }
// ]
```

### `POST /achievements/{key}/complete`

Mark a milestone as completed for a user. Use for API-triggered milestones.

Docs: https://docs.trophy.so/api-reference/endpoints/achievements/mark-an-achievement-as-completed.md

```ts
// Complete an achievement for a user
await trophy.achievements.complete(
  "finish-onboarding", 
  {
    user: { id: "user-123" }
  }
);

// Returns completionId, achievement
// object, and any points awarded
```

## Built for production workloads

Reliable infrastructure designed for performance at scale.

- **99.9%** Uptime SLA
- **200ms** p95 API Latency
- **180M** Monthly API Requests
- **1M+** Users Tracked

## Code examples

### get-achievements.ts

```ts
// Fetch and display achievements

const achievements = await trophy.users
  .achievements("user-123");

// Display badges
for (const a of achievements) {
  console.log(a.name, a.badgeUrl);
}
```

## FAQ

### What is the difference between milestones and badges?

In Trophy, badges are part of milestones, not a separate API. A milestone is a goal a user can reach; each milestone has a badge — an image that represents the accomplishment. You configure both the trigger conditions and badge for each milestone in the dashboard.

### How do I trigger milestones automatically?

Trophy's milestones API evaluates three trigger types: metric thresholds (e.g., "wrote 10,000 words"), streak lengths (e.g., "7-day streak"), and direct API calls (e.g., "profile completed") for custom logic. Triggers are evaluated automatically whenever you send a metric event — no polling or scheduled jobs needed.

### How do I award badges programmatically with custom images?

Upload any badge image when creating a milestone in the Trophy dashboard. Trophy hosts image files and returns the badge URL in every API response, so you can award badges programmatically and render them in your app without managing your own asset storage. Alternatively if you already have asset storage, you can pass a custom badge URL to Trophy directly.

### How do I show milestone progress to users?

Use the [get milestones](https://docs.trophy.so/api-reference/endpoints/users/get-a-users-completed-achievements) endpoint to fetch both completed and in-progress milestones. The response includes progress data so you can render progress bars, completion percentages and rarity statistics.

### Can I use milestones for onboarding?

Yes, Trophy's milestones API is well-suited to onboarding sequences — "completed profile", "first project created", "invited a teammate" — triggered via the API when users complete each step. Across Trophy's platform, users who complete a milestone on their first day retain at 33.42% at day 30, compared to 20.36% for users who don't. so designing the first session so a milestone fires before the user leaves is one of the highest-leverage retention decisions you can make.

### Can I display badges in React, React Native, or mobile apps?

Yes. Adding milestones to any app with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) to handle trigger evaluation and completion logic on your backend. The API returns badge image URLs and completion data that you can render in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework.

### Should I use Game Center or a milestones API?

Use Game Center if you're building an iOS or macOS game and want milestones shown in Apple's built-in UI. Use a milestones API like Trophy if your product runs on the web or across platforms, or isn't a game. Trophy keeps milestones in your own UI and out of a single app store.

### How do milestones work for a non-game or SaaS app?

The same as any other user action. You send an event with one API call when a user does something worth rewarding, and Trophy tracks progress and unlocks the milestone. You then fetch the result to display it anywhere in your app, on web or mobile.

### Can I use Trophy alongside Game Center or Google Play Games?

Yes. Some teams keep platform milestones in Game Center or Google Play Games for their native game builds. They use Trophy for the web and non-game surfaces those store APIs don't reach, and the two run independently.

### Is the milestones API the same as an achievements API?

Yes. Milestones are Trophy's name for in-app achievements, and the API uses the achievements name throughout: endpoints like /achievements/{key}/complete and /users/{id}/achievements, the achievements array in metric event responses, and the achievement.completed webhook. If you're looking for an app achievements API, this is it.
