Challenges

Challenges are time-limited goals that users can join and complete for rewards. They create short-term engagement bursts.

How it works

1. Admin creates a challenge with start/end dates, goal type, and rewards. An event_count challenge also names the event it counts (event_name).
2. Users discover active challenges and opt in (join)
3. Progress is tracked automatically based on the goal type, counting activity from the challenge's start
4. When a user meets the goal, they receive XP and/or an achievement

SDK usage

Get active challenges

const challenges = await client.challenges.getActive();
// Returns the challenges running now:
// [
//   {
//     id: "…",
//     name: "7-Day Fitness Sprint",
//     starts_at: "2025-01-13T00:00:00Z",
//     ends_at: "2025-01-20T00:00:00Z",
//     criteria: { type: "event_count", value: 7 },
//     reward: { xp: 300, achievement_id: null }
//   }
// ]

Get the user's progress

const progress = await client.challenges.getProgress(challengeId);
// { challenge_id, progress: 0.43, completed: false, claimed: false, completed_at, claimed_at }

progress is the fraction of the goal reached, from 0 to 1. GET /v1/client/challenges returns the active challenges with the caller's user_progress, user_status and is_joined on each.

Join a challenge

The SDK has no join method. Join over HTTP with the user's session:

POST /v1/client/challenges/:challengeId/join

Joining is idempotent; a second join returns the existing membership.

Get my challenges

GET /v1/client/challenges/mine

Returns every challenge the user joined, newest first, with its status (active, completed or failed) and the challenge's name, goal and dates.

Goal types

Counting one event

An event_count challenge counts one event, named by event_name, matched exactly against the names your app tracks. A "10 workouts this week" challenge with event_name: "workout_completed" completes on the user's tenth workout_completed event; their other events don't count. event_name is required when you create an event_count challenge and rejected on the other goal types.

An event_count challenge created before event_name existed has event_name: null. It is skipped: progress stays where it is and the challenge never completes. Set event_name on it (PATCH the challenge, or amba_challenges_update) to turn it on; progress then counts the named event from the challenge's start.

When progress updates

Amba evaluates challenges about every 5 minutes, after the app's activity. A participant's user_progress and completion catch up within about 5 minutes of the event, XP or streak that moves them. Progress counts activity since the challenge's start_at, including activity from before the user joined, so a user who already did the work completes on the next evaluation after joining.

On completion, Amba:

• marks the participant completed and emits gamification.challenge.completed;
• grants reward_xp, emitting gamification.xp.granted, and one gamification.level.up for each level the reward crosses;
• unlocks reward_achievement_id.

Your webhooks subscribed to those events receive them. Each reward is granted once per participant. A few minutes after a challenge's end_at, participants still short of the goal are marked failed.

Challenges that ended before 2026-10-10, when Amba began evaluating challenges, are left exactly as they were: their participants are not completed, failed or rewarded.

Admin API reference

Client API reference

MCP tools

Example

Agent: "Create a challenge for 10 workouts this week"

amba_challenges_create({
  project_id: "proj_xxx",
  name: "10 Workouts",
  start_at: "2025-01-13T00:00:00Z",
  end_at: "2025-01-20T00:00:00Z",
  goal_type: "event_count",
  event_name: "workout_completed",
  goal_value: 10,
  reward_xp: 300
})

Agent: "Create a weekend XP challenge"

amba_challenges_create({
  project_id: "proj_xxx",
  name: "Weekend XP Blitz",
  description: "Earn 500 XP this weekend for a bonus reward!",
  start_at: "2025-01-18T00:00:00Z",
  end_at: "2025-01-20T00:00:00Z",
  goal_type: "xp_earned",
  goal_value: 500,
  reward_xp: 200,
  reward_achievement_id: "achievement_weekend_warrior"
})