---
title: Metrics API
canonical_url: "https://trophy.so/developers/metrics"
description: "Track user events and behavior with the Trophy Metrics API and SDK. Send activity events, query aggregates, and power gamification features like streaks, achievements, and leaderboards. SDKs for Node.js, Python, Go, Java, PHP, Ruby, and .NET."
---

# Track user events in minutes

Send a single event to power your entire gamification stack. Metrics power streaks, achievements, points, leaderboards, and analytics.

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

## Quickstart: send an event and read totals

Metrics are the foundation of Trophy. Send one event to power streaks, achievements, points, and leaderboards, then query the user’s aggregated totals.

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

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

// 1. Track a user action — this powers the rest of the gamification stack
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);
console.log("Unlocked achievements:", eventResponse.achievements?.length);
console.log("Current streak:", eventResponse.currentStreak?.length);

// 2. Query all metrics for a user (profile, progress, analytics)
const metrics = await trophy.users.allMetrics("user-123");

for (const metric of metrics) {
  console.log(metric.key, metric.current);
}
```

## Why use Trophy for event tracking?

Building a reliable event tracking pipeline that powers gamification features is harder than it looks.

| Consideration | Trophy | Build in-house | Why it matters |
| --- | --- | --- | --- |
| Integration Time | 1 API call to start tracking events. Full integration in hours. | Build event ingestion pipeline, storage layer, aggregation logic, and API endpoints. Expect 4-8 weeks. | Event pipelines seem simple until you need to handle deduplication, ordering, and fan-out to downstream features like streaks and achievements. |
| Reliability | 99.99% uptime with built-in idempotency and exactly-once processing guarantees. | You must solve idempotency, retry logic, and exactly-once semantics yourself — especially tricky when events fan out to multiple systems. | A missed or duplicated event can break a user's streak, double-award an achievement, or corrupt a leaderboard. Getting this right is critical. |
| Scalability | Trophy processes hundreds of millions of events daily with automatic scaling. | Each growth milestone requires re-evaluating your pipeline: batching strategies, queue sizing, database partitioning, and more. | Event volume grows with your user base. A pipeline that works at 10K events/day can fail at 10M without significant re-architecture. |
| Ongoing Maintenance | Zero maintenance. Trophy handles infrastructure, monitoring, and updates. | Ongoing monitoring, schema migrations, pipeline health checks, and on-call rotations for event processing failures. | Event pipelines are operationally expensive. Alert fatigue from transient failures and data drift can consume engineering time. |
| Feature Development | New metric types, aggregation modes, and attribute filters ship regularly. | Each new metric type or aggregation requires schema changes, migration scripts, and downstream updates across all consuming features. | Your metrics requirements will evolve as your product grows. Building flexibility in from day one is expensive; retrofitting it later is worse. |

## Metrics endpoints

Track user interactions and query aggregated data. The metrics.event endpoint is the foundation that powers all other gamification features.

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

Send a metric event for a user. This is the core endpoint that powers all gamification features including streaks, achievements, points, and leaderboards.

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 powers:
// - Streak tracking
// - Achievement progress
// - Points accumulation
// - Leaderboard rankings
```

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

Get a single user's progress against all active metrics.

Docs: https://docs.trophy.so/api-reference/endpoints/users/get-all-metrics-for-a-user.md

```ts
// Query user metrics
const metrics = await trophy.users.allMetrics("user-123");

// Response:
// [
//   { key: "words-written", name: "Words written",
//     status: "active", current: 4500, achievements: [...] }
// ]
```

## Code examples

### track-action.ts

```ts
// Track lesson completion

async function completeLesson(userId, lessonId) {
  // Your business logic
  await saveProgress(userId, lessonId);

  // Track in Trophy
  await trophy.metrics.event(
    "lessons",
    { user: { id: userId }, value: 1 }
  );
}
```

## FAQ

### What is a metric event?

A metric event is any user action you want to track — completing a lesson, writing words, making a purchase. You send a single API call with the metric key, user ID, and a value, and Trophy automatically updates streaks, achievements, points, and leaderboards.

### How does event tracking power other gamification features?

Metrics are the foundation of Trophy. When you send a metric event, Trophy checks it against all configured features: it extends streaks, evaluates achievement thresholds, awards points, and updates leaderboard rankings — all from that one API call.

### Can I track custom user behavior and activity?

Yes. You define your own metric keys (e.g., "lessons", "purchases", "workouts") in the dashboard, then send events with any numeric value. You can also attach custom attributes for filtering and segmentation.

### What SDKs are available for event tracking?

Trophy offers type-safe server-side SDKs for Node.js, Python, Go, Java, PHP, Ruby, and .NET. All SDKs provide the same simple interface for sending metric events and querying user data.

### Can I use Trophy with React, React Native, or mobile apps?

Yes. Trophy's server-side SDKs handle event tracking and gamification logic from your backend, and you fetch the data to display in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework. This keeps your API key secure and works with any client.

### Can I query a user's aggregated metrics?

Yes. The [get all metrics](https://docs.trophy.so/api-reference/endpoints/users/get-all-metrics-for-a-user) endpoint returns a user's progress against all active metrics, including current totals and related achievements. This is useful for rendering dashboards and progress views in your app.