Streaks

Track consecutive user engagement with configurable streak mechanics, grace periods, and freezes.

Streaks track consecutive user engagement over time. Define a qualifying event (like app_open or workout_completed), and Amba automatically tracks current count, longest count, and streak status.

How it works

Admin defines a streak definition with a qualifying event and period
When a user tracks the qualifying event, their streak is automatically updated
If the user misses a period, the streak resets (unless a grace period or freeze is configured)
Streak evaluation also runs daily in the background to catch broken streaks

SDK usage

Get user's streaks

const streaks = await client.streaks.getAll();
// Returns all streak states with definitions

Each streak includes:

{
  current_count: 7,
  longest_count: 14,
  last_qualified_at: "2025-01-14T10:30:00Z",
  status: "active",
  streak_definitions: {
    name: "Daily Workout",
    qualifying_event: "workout_completed",
    period: "daily"
  }
}

Qualify a streak manually

// Usually automatic via event tracking, but you can also qualify directly:
await client.streaks.qualify('streak_def_xxx');

Automatic qualification

When you track an event that matches a streak's qualifying_event, the streak is automatically qualified:

// This both tracks the event AND qualifies the "Daily Workout" streak
await client.track('workout_completed', { duration: 30 });

Streak mechanics

Period

daily — user must qualify once per calendar day
weekly — user must qualify once per calendar week

Grace period

Set grace_period_hours to give users extra time before their streak breaks. For example, a 6-hour grace period means the user has until 6 AM the next day.

Streak freezes

When freeze_enabled is true, users can freeze their streak to prevent it from breaking. max_freezes controls how many freezes are allowed per period.

Admin API reference

Method	Path	Description
`POST`	`/admin/streaks`	Create streak definition
`GET`	`/admin/streaks`	List streak definitions

Client API reference

Method	Path	Description
`GET`	`/client/streaks`	Get user's streak states
`POST`	`/client/streaks/:id/qualify`	Record qualifying event

POST /client/streaks/:id/qualify

Records a qualifying event for a streak. Handles:

Already qualified today (returns current state, no-op)
Consecutive day (increments count)
Broken streak (resets to 1)

Response:

{
  "data": {
    "id": "uuid",
    "current_count": 8,
    "longest_count": 14,
    "last_qualified_at": "2025-01-15T10:30:00Z",
    "status": "active",
    "current_period_start": "2025-01-08"
  }
}

MCP tools

Tool	Description
`amba_create_streak`	Create a streak definition with qualifying event, period, grace, and freeze settings

Example

Agent: "Create a daily login streak with a 6-hour grace period"

amba_create_streak({
  project_id: "proj_xxx",
  name: "Daily Login",
  qualifying_event: "app_open",
  period: "daily",
  grace_period_hours: 6,
  freeze_enabled: true,
  max_freezes: 2
})

Reading streaks in Expo

import { useEffect, useState } from 'react';
import { Amba } from '@amba/expo';
 
function StreakCard() {
  const [streaks, setStreaks] = useState<Awaited<ReturnType<typeof Amba.streaks.getAll>>>([]);
 
  useEffect(() => {
    Amba.streaks.getAll().then(setStreaks);
  }, []);
 
  const daily = streaks.find((s) => s.streak_id === 'daily_login');
 
  return (
    <View>
      <Text>Current streak: {daily?.current_count ?? 0} days</Text>
      <Text>Longest streak: {daily?.longest_count ?? 0} days</Text>
    </View>
  );
}

Database tables

Table	Purpose
`streak_definitions`	Definitions with qualifying event, period, grace, freeze settings
`user_streaks`	Per-user streak state (current count, longest, status)
`streak_events`	Event log (increment, reset, freeze)

On this page