Challenge Progress
Challenge Progress records the overall state of a single end user's engagement with a specific challenge. It tracks how much cumulative progress the user has accumulated so far, whether the challenge is still winnable, and key lifecycle timestamps.
Challenge Progress records are system-managed — they are created and updated automatically as Challenge Log entries are processed. They cannot be created, updated, or deleted via the API.
The Challenge defines the rules (completionTargetValue, aggregation method, period). The Challenge Progress is the running summary of a specific user's journey against those rules.
How it works
- First log entry arrives — when a
Challenge Logis created for a user on a challenge for the first time, a Challenge Progress record is automatically created withchallengeProgressStatus: in_progressandchallengeStartedAtstamped toactivityAtfield of the Challenge Log API. - Progress accumulates — each
Challenge Logentry adds tocurrentProgressValueaccording to the challenge'saggregationMethod(sumorcount). - Challenge completed — when
currentProgressValuereaches the challenge'scompletionTargetValue, the status transitions tocompletedandchallengeCompletedAtis stamped with theactivityAtfield of the Challenge Log API. - Challenge failed — when the challenge's aggregation period ends and
currentProgressValuehas not reachedcompletionTargetValue, the status transitions tofailedandchallengeFailedAtis stamped. - Task progress surfaced — when listing Challenge 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 |
|---|---|---|
challengeId | UUID | ID of the parent challenge this progress record belongs to. Indexed. |
uniqueIdentifier | string | Auto-generated composite key: challengeId + ownedById. It is unique when challengeProgressStatus value is in_progress. |
Progress & status
| Field | Type | Default | Description |
|---|---|---|---|
currentProgressValue | number | 0 | The user's cumulative progress value so far — the running total of all Challenge Log contributions. Compared against the challenge's completionTargetValue to determine completion. |
challengeProgressStatus | enum | in_progress | Current status of the challenge for this user. See statuses below. |
Timestamps
| Field | Type | Description |
|---|---|---|
challengeStartedAt | datetime | When the user first engaged with this challenge. Defaults to the creation time. |
challengeCompletedAt | datetime | Stamped when challengeProgressStatus transitions to completed. |
challengeFailedAt | datetime | Stamped when challengeProgressStatus transitions to failed. |
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 challenge is active — the user has not yet hit the target, and the challenge window has not closed. |
completed | The user's currentProgressValue reached the challenge's completionTargetValue — the challenge is won. |
failed | The challenge window ended before the user reached the target — the challenge is lost. |
Unlike streaks (which break when a single period is missed), challenges only fail when the entire challenge window closes without the target being met. Users can still complete a challenge right up to the last moment of the period.
The taskProgress field
When you list Challenge 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 a separate API call.
Code
For a monthly challenge requiring 8 visits,
currentProgressValue: 3means the user has visited 3 times this month.taskProgressreflects the same value since challenge progress accumulates within the single challenge period.
Real-world examples
🛍️ E-commerce — monthly spend challenge (in progress)
A user is working toward a monthly challenge requiring $500 total spend (aggregationMethod: sum, completionTargetValue: 500):
Code
The user needs $312.50 more to complete the challenge before 30 April.
☕ Food & Beverage — monthly visit challenge (completed)
A user completes a challenge requiring 8 café visits in a month (aggregationMethod: count, completionTargetValue: 8):
Code
🏋️ Fitness — weekly step challenge (failed)
A user fails to accumulate 100,000 steps in a week (aggregationMethod: sum, completionTargetValue: 100000):
Code
The user accumulated 61,420 steps — 38,580 short of the 100,000 target when the weekly window closed.
Fetching a user's challenge progress
As an end user — get your progress on a specific challenge:
Code
As an admin — list all progress records for a challenge:
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 |
Challenge Progress records cannot be created, updated, or deleted via the API. They are managed exclusively by the platform as Challenge Log entries are processed.
Related resources
| Resource | Description |
|---|---|
| Challenge | The parent challenge configuration that this progress record belongs to |
| Challenge Log | Individual activity log entries that drive progress updates |
| Milestone | Reward checkpoints linked to the parent challenge |
| Reward Log | Reward entries issued when a milestone threshold is crossed |
| Streak Progress | Equivalent progress tracking for streaks |
API reference
See the API Reference for full request/response schemas and interactive examples for:
GET /schema/challenge_progress/record— list challenge progress recordsGET /schema/challenge_progress/record/{id}— get a challenge progress record by ID