Deck progress

The deck progress object captures how well you know a deck at a point in time. It includes its retention and the number of cards in each learning stage.

Recall records one snapshot per day, so you can retrieve the latest snapshot or a history of snapshots over time.

To know when the next review is and how many cards are currently due, see due_cards_count and next_review_at on the deck object instead.

Endpoints

GET   /v1/decks/:id/progress           # Get the latest deck progress
GET   /v1/decks/:id/progress/history   # List deck progress over time

The deck progress object

A deck progress object is a daily snapshot of a deck's learning state. Numbers are updated several times per day.

retention is available on all plans. The card stage counts (learning_cards_count, mature_cards_count, relearning_cards_count, suspended_cards_count, unscheduled_cards_count, and young_cards_count) require the Pro plan. On the free plan, each card stage count returns null.

{
  "object": "deck_progress",
  "deck": "deck_5gvuzRdHW2ac",
  "date": "2025-12-01",
  "retention": 45,
  "learning_cards_count": 10,
  "mature_cards_count": 43,
  "relearning_cards_count": 3,
  "suspended_cards_count": 5,
  "unscheduled_cards_count": 82,
  "young_cards_count": 34,
}

Get the latest deck progress

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac/progress \
  -u YOUR_API_KEY:

There are no parameters for this endpoint.

You can also retrieve the latest progress alongside a deck by expanding progress on any deck endpoint:

curl "https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac?expand=progress" \
  -u YOUR_API_KEY:

Returns

Returns the most recent deck progress object, or null if the deck has no progress data yet (for example, a deck whose cards have never been reviewed).

List deck progress over time

curl https://api.recall.cards/v1/decks/deck_5gvuzRdHW2ac/progress/history \
  -u YOUR_API_KEY:

Returns deck progress snapshots ordered by date, oldest first. When no range is given, the last 90 days are returned. Use start_date and end_date to request a specific range.

Recall records one snapshot per day once a deck starts accruing stats, carrying the previous values forward on days without reviews, so the series is continuous by default. Days before a deck's first snapshot are not present.

Returns

{
  "object": "list",
  "has_more": false,
  "data": [
    // Deck progress objects, oldest first
  ],
}