Streaks API

The API for streaks

Add daily or weekly streaks to your app in under an hour. Trophy handles timezone logic, daylight savings transitions, and freeze mechanics out of the box. Start for free, scale to millions of users.

Get API key API reference

SDKs for

Quickstart

Quickstart: track and read a streak

Send a metric event to extend a streak, then fetch the user’s current streak length, expiry, and history. Trophy handles timezone evaluation and freeze consumption automatically.

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

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

// 1. Track activity that powers the streak
const eventResponse = await trophy.metrics.event("lessons", {
  user: { id: "user-123" },
  value: 1,
});

console.log("Current streak:", eventResponse.currentStreak?.length);

// 2. Fetch full streak state for UI (length, expires, history)
const streak = await trophy.users.streak("user-123");

console.log("Length:", streak.length);
console.log("Expires:", streak.expires);
console.log("History periods:", streak.streakHistory?.length);

// 3. Optionally grant a freeze so one missed day does not reset progress
await trophy.admin.streaks.freezes.create({
  freezes: [{ userId: "user-123" }],
});

Buy vs. build

Why use Trophy's streak API?

Streak mechanics are deceptively complex. Timezone handling, daylight savings transitions, freeze logic, and period boundaries each introduce edge cases that are hard to test exhaustively and expensive to maintain over time.

Key Considerations

Build

Why does it matter?

Integration Time

Streaks work automatically from metric events. Zero streak-specific code needed.

Build period tracking, expiration logic, timezone handling, freeze mechanics, and streak history. Expect 4-6 weeks.

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.

You must handle users changing time zones mid-streak, daylight saving transitions, and period boundary edge cases — all without breaking active streaks.

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 millions of times a day without batch jobs or cron-based processing.

Daily streak expiration checks for large user bases require carefully tuned batch processing, often competing for database resources during peak hours.

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.

Changing streak frequency (daily to weekly) or adding freeze mechanics requires schema changes, migration scripts, and careful handling of existing streaks.

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.

Each new streak feature — freezes, grace periods, multiple streak types — adds complexity to an already tricky time-based system.

Streak mechanics evolve as you learn what drives retention. The ability to iterate quickly without re-engineering your time logic is critical.

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 millions of times a day 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.

Concepts

How a daily streak works

A streak counts consecutive periods of activity. Most implementations track the same core fields: a current streak count (current_streak), a longest or “best” streak (longest_streak), and the date the user was last active (last_active_date). Trophy’s API exposes these same concepts as length, started, expires, and streakHistory.

Generic concept	Trophy field
Current streak count	length
Streak start date	started
When the streak breaks if not extended	expires
Past streak periods (and best streak)	streakHistory

Increment logic. If the user was already active today, the streak stays the same. If they return the next calendar day, the streak increments by one. If they skip more than one period, the streak resets to zero.

Timezones. Store timestamps in UTC, but evaluate streaks in the user’s local time. A user who logs activity at 11:55 PM and again at 12:05 AM should keep their streak, not lose it. Trophy handles timezone-aware evaluation and daylight savings transitions automatically.

Streak freezes. A freeze (sometimes called a “grace day”) protects a streak when a user misses a single period, so one skipped day does not reset their progress. Trophy can grant and consume freezes automatically, and you can manage them programmatically through the streak freeze API.

Endpoints

Streak API endpoints

Trophy tracks streaks and sends streak reminder push notifications and emails through a single API call. Use Trophy's streak tracking API to record consecutive user activity, maintain daily and weekly streak history, and manage freeze mechanics automatically from the metric events you send.

POST/metrics/{key}/eventView docs

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

Path Parameters

keystringrequired

Unique reference of the metric as set when created.

Request Body

userUserrequired

The user that triggered the event (must include id).

valuenumberrequired

The value to add to the user's current total for the given metric.

Response

eventIdstring

Unique identifier for the created event.

totalnumber

The user's new total for this metric.

currentStreakStreak

The user's current streak status.

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:
// - Records user activity
// - Computes streak data
// - Returns new streak data

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 platform to effortlessly build retentive user experiences. Get a team that's 100% focused on retention.

Get started API 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}
  />
);

Gamification UI library

Pixel-perfect streaks UI components

Use our open-source gamification UI components as the foundation for your design system. Customize as you see fit. Designed to work perfectly with the Trophy API.

Get started UI library

One-command install: Add any component to your project with a single CLI command. No extra dependencies to manage.
Fully customizable: Every component lives in your codebase. Tweak styles, layout, and behavior to match your brand.
Open-source.: MIT licensed and community-driven. Use in personal projects or production apps without restrictions.

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.

How do daily streaks work?

Trophy's daily streak tracking API records consecutive periods of user activity automatically. When you send a metric event, Trophy extends the user's streak for that period. If a user misses a day, week, or month, 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 activity per week, and so on.

What is the streak freeze API?

Trophy can automatically grant and consume streak freezes to keep streaks alive. Trophy's streak freeze API lets you programmatically manage users' streaks with more control. For example grant an extra freeze to premium users and Trophy applies it automatically the next time a user misses a day.

How do I build a habit-tracking feature with streaks?

Send a metric event to Trophy each time a user completes a target action and Trophy's streak API handles the rest — consecutive activity tracking, timezone-aware expiration and daylight savings while tracking streak history. Fetch streak data via the API to render streak UI in your frontend.

How do streaks improve user retention?

Streaks create a psychological commitment loop where users return to avoid breaking their streak, which drives daily active usage and builds habitual engagement. Across Trophy's platform, apps using streak freeze features average 17-day streaks for users who pass the 7-day mark, compared to 11 days for apps without freezes. Trophy can also send streak reminder emails and push notifications to users who are close to breaking their streak to increase average streak length and retention.

Can I show streaks in React, React Native, or mobile apps?

Yes. Adding a mobile app streak feature with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, .NET) to 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.

Get started

Up and running in minutes

Start

Start building

Integrate in minutes, interpret in hours. No credit card required.

Start for free

Explore

See what's possible

Explore how Trophy can increase user engagement and retention.

Book a call

Compare

Compare plans

Understand the free tier limits and Trophy's usage-based model.

See pricing