Metrics API
Track user events in minutes
Send a single event to power your entire gamification stack. Metrics power streaks, achievements, points, leaderboards, and analytics.
SDKs for
Endpoints
Metrics endpoints
Track user interactions and query aggregated data. The metrics.event endpoint is the foundation that powers all other gamification features.
Send a metric event for a user. This is the core endpoint that powers all gamification features including streaks, achievements, points, and leaderboards.
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.
attributesobjectEvent attributes as key-value pairs matching attributes set up in the dashboard.
Response
eventIdstringUnique identifier for the created event.
totalnumberThe user's new total for this metric.
achievementsAchievement[]Achievements completed by this event.
currentStreakStreakThe user's current streak status.
pointsobjectPoints awarded by this event, keyed by points system.
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 powers:
// - Streak tracking
// - Achievement progress
// - Points accumulation
// - Leaderboard rankingsGet a single user's progress against all active metrics.
Path Parameters
idstringrequiredID of the user.
Response
keystringUnique key of the metric.
namestringDisplay name of the metric.
currentnumberThe user's current total for this metric.
achievementsAchievement[]Related achievements and their progress.
Example
import { TrophyApiClient } from '@trophyso/node';
const trophy = new TrophyApiClient({
apiKey: 'YOUR_API_KEY'
});
// Query user metrics
const metrics = await trophy.users.allMetrics("user-123");
// Response:
// [
// { key: "words-written", name: "Words written",
// status: "active", current: 4500, achievements: [...] }
// ]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.
// 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 }
);
}Built for production workloads
Reliable infrastructure designed for performance at scale.
- API Uptime
- 99.99%
- Avg Response Time
- <50ms
- Integration Time
- < 1 hour
- API Calls / Month
- 10M+
Buy vs. Build
Why use Trophy for event tracking?
Building a reliable event tracking pipeline that powers gamification features is harder than it looks.
| Key Considerations | Build | Why does it matter? | |
|---|---|---|---|
| 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. |
Integration Time
1 API call to start tracking events. Full integration in hours.
Build
Build event ingestion pipeline, storage layer, aggregation logic, and API endpoints. Expect 4-8 weeks.
Why does it matter?
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.
Build
You must solve idempotency, retry logic, and exactly-once semantics yourself — especially tricky when events fan out to multiple systems.
Why does it matter?
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.
Build
Each growth milestone requires re-evaluating your pipeline: batching strategies, queue sizing, database partitioning, and more.
Why does it matter?
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.
Build
Ongoing monitoring, schema migrations, pipeline health checks, and on-call rotations for event processing failures.
Why does it matter?
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.
Build
Each new metric type or aggregation requires schema changes, migration scripts, and downstream updates across all consuming features.
Why does it matter?
Your metrics requirements will evolve as your product grows. Building flexibility in from day one is expensive; retrofitting it later is worse.
FAQ
Metrics API FAQ
Have a different question and can’t find the answer you’re looking for? Send us an email.
- 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 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.
Gamification infrastructure that retains users
Boost retention and customer lifetime value. Try for free up to 100 MAUs.
