> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaks

> Learn how to use streaks in a gamified product experience with Trophy.

<h2 id="what-are-streaks">
  What are Streaks?
</h2>

A streak is a period of consecutive days, weeks or months that a user has performed a key action on your platform. Streaks have been shown to meaningfully increase retention, particularly when the user action being tracked aligns with the core value of your product.

<h2 id="streak-frequency">
  Streak Frequency
</h2>

Streaks in Trophy can be **daily, weekly or monthly**. This means that a user must meet their [streak conditions](#streak-conditions) at least once every calendar day, week or month to maintain their streak.

If you've [configured time zones](/features/users#param-tz) for your users, Trophy will automatically track each user's streak in their local time zone (including taking into account when users change time zones) and keep streaks in tact.

<Note>
  Trophy automatically computes streak data for every streak frequency, meaning you can switch at any time.
</Note>

<h2 id="streak-conditions">
  Streak Conditions
</h2>

In Trophy you can set the thresholds that a user must meet in order to extend their streak based on your configured [Metrics](/features/metrics).

You can choose which metrics should be part of your streak, and for those that you chose, you can set a custom threshold that users must meet.

<Frame>
  <img height="200" width="100%" noZoom src="https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/streaks/streak_config.png?fit=max&auto=format&n=rGjOHIeZYrVU9hOo&q=85&s=337a1e05f702ecf91bf69f9bf5e375c7" data-path="assets/features/streaks/streak_config.png" />
</Frame>

When combining metrics in this way, you can choose between two evaluation modes:

* `ALL` means a user must meet every metric threshold to extend their streak
* `OR` means a user only has to meet one of your metric thresholds to extend their streak

In this way you can design your streak logic to match your application use case.

<h2 id="streak-freezes">
  Streak Freezes
</h2>

Streak freezes help users keep their streaks for longer by allowing them to miss periods without it resetting to zero. This helps keep streaks motivating even if users don't maintain a perfect usage habit.

<Frame>
  <img height="200" width="100%" noZoom src="https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/streaks/freezes_config.png?fit=max&auto=format&n=rGjOHIeZYrVU9hOo&q=85&s=01afad6182534bb803e5ff6c568f8437" data-path="assets/features/streaks/freezes_config.png" />
</Frame>

Streak freezes are optional in Trophy but can be configured on the [streaks page](https://app.trophy.so/streaks) of the Trophy dashboard.

<h3 id="granting-initial-freezes">
  Granting Initial Freezes
</h3>

You can configure any number of arbitrary freezes to grant to new users when you first identify them with Trophy.

<Tip>
  Giving users too many freezes may decrease their perceived value, but granting too few freezes might result it a higher number of lost streaks. A good starting point is one freeze per user, but the trick is to experiment!
</Tip>

<h3 id="freeze-accumulation">
  Freeze Accumulation
</h3>

As users use up streak freezes, they'll need a continuous supply of new ones to keep them going. To facilitate this, Trophy can automatically grant streak freezes to users over time. You can choose an arbitrary number of days over which to grant an arbitrary number of freezes to each user.

If you've [configured time zones](/features/users#param-tz) for your users, Trophy will automatically consume freezes at midnight in the user's time zone when necessary to extend their streak, and if any new freezes are due to be granted to a user, they will be granted up to ten minutes later.

<h3 id="maximum-freeze-count">
  Maximum Freeze Count
</h3>

In Trophy you also configure the maximum number of freezes that each user can have, up to a limit of 100. [Freeze accumulation](#freeze-accumulation) will only ever grant freezes up to this limit.

<h2 id="tracking-streaks">
  Tracking Streaks
</h2>

Trophy automatically calculates streaks for all users based on the [metric events](/features/events#tracking-metric-events) you report to Trophy.

There's no extra work required to track streaks, and you can start using them right away. Just make sure that streaks are enabled in the Trophy dashboard.

<Tip>
  For a full walk through on how to set up a streak feature using Trophy, check out our [official guide](/guides/how-to-build-a-streaks-feature).
</Tip>

<h2 id="streak-personalization">
  Streak Personalization
</h2>

Trophy can support users personalizing how their streak works within guardrails you set for them.

To do this, turn on streak personalization in the [streaks page](https://app.trophy.so/streaks) of the Trophy dashboard.

<Frame>
  <video autoPlay muted loop playsInline className="w-full aspect-15/4" height="200" width="100%" noZoom src="https://mintcdn.com/trophy/nbAC5EwP11UAmbTX/assets/features/streaks/streak_personalization.mp4?fit=max&auto=format&n=nbAC5EwP11UAmbTX&q=85&s=236446a22d87ade330686a5287f17b10" data-path="assets/features/streaks/streak_personalization.mp4" />
</Frame>

Once enabled, users will be able to customize the [streak conditions](#streak-conditions) that they must meet to extend their streak, including streak evaluation mode and the threshold for each metric, through user preferences.

<Tip>
  To learn more about how to set user preferences for a specific user, read the dedicated documentation on [user preferences](/features/users#streak-preferences).
</Tip>

<h2 id="managing-streaks">
  Managing Streaks
</h2>

This section outlines some of the operations you can perform to manage user's streaks in your application.

<h3 id="restoring-a-users-streak">
  Restoring A Users Streak
</h3>

To restore a user's streak, head to the user details page and use the 'Restore Streak' action. Restoring a user's streak sets it to the length it was when they last lost it.

<Tip>
  You can also use the [restore streak admin API](/admin-api/endpoints/streaks/restore-streaks) to restore streaks programmatically.
</Tip>

<Frame>
  <video autoPlay muted loop playsInline className="w-full aspect-15/4" src="https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/streaks/restoring_streaks.mp4?fit=max&auto=format&n=rGjOHIeZYrVU9hOo&q=85&s=b88d313f201522c37507a1c0778fb85d" data-path="assets/features/streaks/restoring_streaks.mp4" />
</Frame>

<h2 id="displaying-streaks">
  Displaying Streaks
</h2>

Trophy exposes streak data in two ways, which can be used to build UI elements within your applications and display streaks to users.

<Tip>
  Check out our [full guide](/guides/how-to-build-a-streaks-feature) on adding a
  streaks feature to your app for more details.
</Tip>

<h3 id="metric-event-response">
  Metric Event Response
</h3>

When you [increment a metric](/features/events#tracking-metric-events) for a user, the [metric API](/api-reference/endpoints/metrics/send-a-metric-change-event) response will include the user's current
streak.

```json Response [expandable] theme={null}
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  "achievements": [
    {
      "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "trigger": "metric",
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "metricName": "Flashcards Flipped",
      "metricValue": 500,
      "name": "500 Flashcards Flipped",
      "description": "Write 500 words in the app.",
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  },
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 10,
      "level": {
        "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
        "key": "bronze",
        "name": "Bronze",
        "description": "Starting level",
        "badgeUrl": null,
        "points": 0
      },
      "added": 10,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 10,
          "date": "2021-01-01T00:00:00Z",
          "total": 10,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "Flashcards Flipped",
            "metricThreshold": 100,
            "points": 10
          }
        }
      ]
    }
  },
  "leaderboards": {
    "daily_champions": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
      "key": "daily_champions",
      "name": "Daily Champions",
      "description": null,
      "rankBy": "metric",
      "runUnit": null,
      "runInterval": 0,
      "maxParticipants": 100,
      "metricName": "Flashcards Flipped",
      "metricKey": "flashcards-flipped",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "previousRank": 50,
      "rank": 12
    }
  }
}
```

This can be used to transactionally trigger UI/UX elements including:

* Showing in-app pop-ups
* Playing sound effects

<h3 id="user-streaks-api">
  User Streaks API
</h3>

The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns the current streak for a single user, along with their recent streak history. Use the `historyPeriods` query parameter to control how many periods to return.

```json Response [expandable] theme={null}
{
  "length": 1,
  "frequency": "weekly",
  "started": "2025-04-02",
  "periodStart": "2025-03-31",
  "periodEnd": "2025-04-05",
  "expires": "2025-04-12",
  "rank": 5,
  "streakHistory": [
    {
      "periodStart": "2025-03-02",
      "periodEnd": "2025-03-08",
      "length": 9
    },
    {
      "periodStart": "2025-03-09",
      "periodEnd": "2025-03-15",
      "length": 0
    },
    {
      "periodStart": "2025-03-16",
      "periodEnd": "2025-03-22",
      "length": 0
    },
    {
      "periodStart": "2025-03-23",
      "periodEnd": "2025-03-29",
      "length": 1
    },
    {
      "periodStart": "2025-03-30",
      "periodEnd": "2025-04-05",
      "length": 2
    },
    {
      "periodStart": "2025-04-06",
      "periodEnd": "2025-04-12",
      "length": 3
    },
    {
      "periodStart": "2025-04-13",
      "periodEnd": "2025-04-19",
      "length": 4
    }
  ]
}
```

Use this data to display a user's streak history within your application.

<Frame>
  <img height="200" noZoom src="https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/streaks/displaying_streaks.png?fit=max&auto=format&n=rGjOHIeZYrVU9hOo&q=85&s=8ee229b58d2560e950aa968bbc3e7c41" data-path="assets/features/streaks/displaying_streaks.png" />
</Frame>

<h3 id="list-multiple-users-streaks">
  List Multiple User's Streaks
</h3>

If you want to display streaks for multiple users at once, for example to support a friend streak or user group feature, then use the [list user streaks API](/api-reference/endpoints/streaks/get-streaks).

```json [expandable] theme={null}
[
  {
    "userId": "user-123",
    "streakLength": 15,
    "extended": "2025-01-01T05:03:00Z"
  },
  {
    "userId": "user-456",
    "streakLength": 12,
    "extended": "2025-01-01T08:43:00Z"
  },
  {
    "userId": "user-789",
    "streakLength": 0,
    "extended": null
  }
]
```

<h2 id="get-support">
  Get Support
</h2>

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!