Streak Progress
Streak Progress records the overall state of a single end user's engagement with a specific streak. It tracks how many periods the user has completed so far, whether the streak is still alive, and key lifecycle timestamps.
Streak Progress records are system-managed — they are created and updated automatically as Streak Log entries are processed. They cannot be created, updated, or deleted via the API.
The Streak defines the rules (aggregation method, period, target value, milestones). The Streak Progress is the running summary of a specific user's journey against those rules. Individual period-level detail lives in Streak Logs.
How it works
- First log entry arrives — when a
Streak Logis created for a user on a streak for the first time, a Streak Progress record is automatically created withstreakProgressStatus: in_progressandstreakStartedAtstamped toactivityAtpassed in the StreakLog API. - Progress accumulates — each period the user meets the aggregation target,
currentProgressValueincrements. - Period missed — if the user fails to meet the aggregation target in a period, the status transitions to
brokenandstreakBrokenAtis stamped. - Streak completed — when
currentProgressValuereaches the streak's total required periods, the status transitions tocompletedandstreakCompletedAtis stamped as peractivityAtfield of the StreakLog API. - Task progress surfaced — when listing Streak Progress records, the response also includes the current Task Progress (
taskProgress) inline, giving a full picture of this-period activity without a separate request.
Fields
Identity & linking
| Field | Type | Description |
|---|---|---|
streakId | UUID | ID of the parent streak this progress record belongs to. Indexed. |
uniqueIdentifier | string | Auto-generated composite key: streakId + ownedById. This field is unique when streakProgressStatus value is in_progress. |
Progress & status
| Field | Type | Default | Description |
|---|---|---|---|
currentProgressValue | number | 0 | The number of periods the user has successfully completed so far in this streak. |
streakProgressStatus | enum | in_progress | Current status of the streak for this user. See statuses below. |
Timestamps
| Field | Type | Description |
|---|---|---|
streakStartedAt | datetime | When the user first engaged with this streak. It takes value from the activityAt field in the StreakLog API. |
streakCompletedAt | datetime | Stamped with the activityAt value of the StreakLog API when streakProgressStatus transitions to completed. |
streakBrokenAt | datetime | Stamped when streakProgressStatus transitions to broken. |
lastTaskContributionAt | datetime | Timestamp of the most recent activityAt field of the StreakLog entry processed for this user. |
lastTaskCompletedAt | datetime | Timestamp of the most recent activityAt field of the StreakLog in which the user fully met the aggregation target. |
Ownership
| Field | Type | Description |
|---|---|---|
ownedById | UUID | ID of the end user this progress record belongs to. |
ownedBy | object | Read-only joined user object. |
Status values
| Status | Meaning |
|---|---|
in_progress | The streak is active — the user has not yet completed all required periods, and has not missed a period. |
completed | The user has met the aggregation target for every required period — the streak is won. |
broken | The user missed a required period — the streak is lost and cannot be recovered. |
The taskProgress field
When you list Streak Progress records, the response automatically includes a taskProgress object inline. This gives a real-time view of the user's activity in the current period without needing a separate API call.
Code
The
taskProgressshows today's accumulated value (42.50) toward the period target — useful for real-time progress bars in the end-user widget.
Real-world examples
🛍️ E-commerce — 7-day daily spend streak
A user is on day 4 of a 7-day streak requiring $50+ spend each day:
Code
The user has completed the 3rd day streak and is on 4th day with zero progress on 4th day
☕ Food & Beverage — 5-visit weekly streak (completed)
A user successfully completes a 4-week streak requiring 3 café visits per week:
Code
🏋️ Fitness — monthly activity streak (broken)
A user missed their February activity target in a 3-month streak:
Code
The user completed January (
currentProgressValue: 1) but failed to hit the February target, so the streak broke on 1 March when the new period opened.
Fetching a user's streak progress
End users can query their own progress. Admins can query all records.
As an end user — get your progress on a specific streak:
Code
As an admin — list all progress records for a streak:
Code
Access & permissions
| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | GET · LIST | Read-only — no CREATE, UPDATE, or DELETE |
| End user | GET · LIST | Can only read their own progress records |
| Guest user | (none) | Not accessible to unauthenticated callers |
Streak Progress records cannot be created, updated, or deleted via the API. They are managed exclusively by the platform as Streak Log entries are processed.
Related resources
| Resource | Description |
|---|---|
| Streak | The parent streak configuration that this progress record belongs to |
| Streak Log | Individual period-level log entries that drive progress updates |
| Milestone | Reward checkpoints linked to the parent streak |
| Reward Log | Reward entries issued when a milestone threshold is crossed |
API reference
See the API Reference for full request/response schemas and interactive examples for:
GET /schema/streak_progress/record— list streak progress recordsGET /schema/streak_progress/record/{id}— get a streak progress record by ID