Streaks API

Add streaks to your app in minutes

Build habit-forming mechanics that drive daily engagement. Track consecutive activity, manage streak freezes, and motivate users to maintain their progress.

Get API KeyAPI Reference
SDKs for
NodeJSGoJava.NETPHPPythonRuby

Endpoints

Streak endpoints

Track consecutive user activity and manage streak mechanics. Streaks are automatically maintained based on metric events you send.

GET/users/{id}/streakView Docs

Get a user's streak data including current length, frequency, and history.

Path Parameters

idstringrequired

ID of the user.

Query Parameters

historyPeriodsinteger

Number of past streak periods to include in streakHistory (default: 7).

Response

lengthnumber

Current streak length.

frequencystring

Streak frequency: "daily", "weekly", or "monthly".

starteddate

Date the current streak started.

expiresdate

When the streak will break if not extended.

streakHistoryStreakPeriod[]

Array of past streak periods with lengths.

Example
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// Fetch user streak data
const streak = await trophy.users.streak("user-123");

// Response:
// {
//   length: 7, 
//   frequency: "daily",
//   started: "2025-04-02",
//   periodStart: "2025-03-31",
//   expires: "2025-04-12",
//   rank: 5, 
//   streakHistory: [...]
// }
POST/streaks/freezesView Docs

Create streak freezes for multiple users. Freezes prevent streak loss when users miss a period.

Request Body

freezesarrayrequired

Array of objects with userId to create freezes for.

Response

issuesIssue[]

Array of warnings or errors for each freeze request.

Example
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// Create streak freezes
await trophy.admin.streaks.freezes.create({
  freezes: [
    { userId: "user-123" }
  ]
});

// Protects streak from breaking

Lightning-Fast Integration

Simple APIs You'll Love

Use our pre-built gamification API to effortlessly build retentive user experiences. Get a team that's 100% focused on retention.

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.
// Fetch and render streak UI

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

// Render streak component
return (
  <StreakBadge
    length={streak.length}
    frequency={streak.frequency}
    expires={streak.expires}
  />
);

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 streaks?

Streak mechanics are deceptively complex — time zones, DST, freezes, and period boundaries make building in-house risky.

Integration Time

Streaks work automatically from metric events. Zero streak-specific code needed.
Build
Build period tracking, expiration logic, timezone handling, freeze mechanics, and streak history. Expect 4-6 weeks.
Why does it matter?
Streaks seem like a simple counter until you factor in time zones, daylight saving transitions, configurable frequencies, and freeze logic.

Reliability

Timezone-aware streak evaluation with automatic DST handling and consistent period boundaries.
Build
You must handle users changing time zones mid-streak, daylight saving transitions, and period boundary edge cases — all without breaking active streaks.
Why does it matter?
A user who logs in at 11:55 PM and again at 12:05 AM shouldn't lose their streak to a timezone bug. These edge cases are notoriously hard to test exhaustively.

Scalability

Trophy evaluates streak expiration across millions of users without batch jobs or cron-based processing.
Build
Daily streak expiration checks for large user bases require carefully tuned batch processing, often competing for database resources during peak hours.
Why does it matter?
As your user base grows, the midnight cron job that checks streak expiration becomes a scaling bottleneck that's hard to distribute across time zones.

Ongoing Maintenance

Streak frequency and freeze rules are configurable in the dashboard. No code changes needed.
Build
Changing streak frequency (daily to weekly) or adding freeze mechanics requires schema changes, migration scripts, and careful handling of existing streaks.
Why does it matter?
Product teams will want to experiment with streak mechanics — different frequencies, freeze policies, grace periods. Each change should be a config update, not a deploy.

Feature Development

Freeze mechanics, streak history, multiple frequencies, and expiration warnings ship regularly.
Build
Each new streak feature — freezes, grace periods, multiple streak types — adds complexity to an already tricky time-based system.
Why does it matter?
Streak mechanics evolve as you learn what drives retention. The ability to iterate quickly without re-engineering your time logic is critical.

FAQ

Streaks & Habit Tracking FAQ

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

How do daily streaks work?
Streaks track consecutive periods of user activity. When you send a metric event, Trophy automatically extends the user's streak. If a user misses a period (day, week, or month depending on your configuration), the streak resets.
Can I configure streak frequency?
Yes. Streaks can be configured as daily, weekly, or monthly in the Trophy dashboard. A daily streak requires activity every day, weekly requires at least one event per week, and so on.
What are streak freezes?
Streak freezes protect a user's streak from breaking when they miss a period. You can grant freezes via the admin API — for example, giving users a freeze as a reward or as part of a premium plan.
How do I build a habit-tracking feature with streaks?
Send a metric event each time the user completes the desired action. Trophy handles the streak logic — tracking consecutive activity, managing timezones, and calculating expiration. Fetch the streak data via the API to render streak UI in your app.
How do streaks improve user retention?
Streaks create a psychological commitment loop — users return to avoid breaking their streak. This drives daily active usage and builds habitual engagement. Trophy handles the mechanics so you can focus on the user experience.
Can I show streaks in React, React Native, or mobile apps?
Yes. Trophy's server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, .NET) manage streak logic on your backend. The API returns streak length, frequency, and expiration data that you can render in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework.

Gamification infrastructure that retains users

Boost retention and customer lifetime value. Try for free up to 100 MAUs.

Get StartedRead Docs
Trophy