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.
Quickstart
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.
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);
}Buy vs. build
Why use Trophy for event tracking?
Building a reliable event tracking pipeline that powers gamification features is harder than it looks.
Integration Time
Reliability
Scalability
Ongoing Maintenance
Feature Development
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.
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.
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 platform 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.
- 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.
Get started