> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taketime.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Progress Stats: Heatmaps, Streaks, and Completion Rate

> Take Time tracks your study completions with a 12-month heatmap, streak counters, and completion rate metrics. Learn what each metric measures.

Take Time automatically records your activity every time you mark a block as done. The stats system tracks completions across study blocks, training exercises, and routine micro-habits to give you a complete picture of your consistency over time.

## The Activity Heatmap

The heatmap displays 12 months of your activity as a GitHub-style grid. Each cell represents one calendar day. The intensity of the cell's color reflects the total number of completions logged on that day — the more you complete, the darker the cell.

What counts toward a day's heatmap intensity:

* **Completed study blocks** — each block you mark done adds to the day's count
* **Individual exercises checked** — each exercise you tick inside a Training block adds separately, not just the block as a whole
* **Individual micro-habits checked** — each habit you tick inside a Routine block adds to the count in the same way

This granular approach rewards you for doing the work inside a block, not just for opening and closing it.

<Tip>
  Focus on building a **streak** rather than maximizing your daily completion count. A modest but unbroken chain of active days compounds into a strong habit far more reliably than occasional high-volume sessions with gaps in between. Even one small completion per day keeps your streak alive and your heatmap warm.
</Tip>

## Streaks

Your streak counts the number of consecutive calendar days on which you logged at least one completion of any kind — a block, an exercise, or a micro-habit. The counter resets to zero if you have a day with no completions at all.

<Info>
  The streak clock resets at **midnight local time**. If you finish a session just before midnight and want it to count toward today rather than tomorrow, make sure you mark it done before the clock turns over.
</Info>

## Completion Rate

Your completion rate is the ratio of completed blocks to total scheduled blocks within the selected time period:

```text theme={null}
completion_rate = completed_blocks / total_blocks
```

A value of `1.0` means you completed every scheduled block. A value of `0.0` means none were completed. Use this metric to calibrate whether your schedule is realistic — a persistently low rate may mean you are over-scheduling rather than under-performing.

## Stats API Response

The stats endpoint returns a summary object for the requested period. Here is a representative response:

```json theme={null}
{
  "total_blocks": 42,
  "completed_blocks": 35,
  "completion_rate": 0.83,
  "streak_days": 7,
  "total_minutes": 2100,
  "heatmap": {
    "2026-06-11": 5,
    "2026-06-10": 3
  }
}
```

| Field              | Type   | Description                                           |
| ------------------ | ------ | ----------------------------------------------------- |
| `total_blocks`     | number | All scheduled blocks in the period                    |
| `completed_blocks` | number | Blocks marked done in the period                      |
| `completion_rate`  | number | Ratio of completed to total (0–1)                     |
| `streak_days`      | number | Current consecutive-day streak                        |
| `total_minutes`    | number | Sum of durations of all completed blocks              |
| `heatmap`          | object | Map of `YYYY-MM-DD` date strings to completion counts |

## Period Filters

When querying stats, pass a `period` parameter to scope the results:

| Value   | Description                           |
| ------- | ------------------------------------- |
| `today` | Current calendar day only             |
| `week`  | Rolling 7-day window ending today     |
| `month` | Rolling 30-day window ending today    |
| `all`   | Entire history since account creation |

## Priority Circle Context

The Priority Circle organizes your activities into three zones — **Main Focus**, **Important**, and **Flexible** — to help you allocate time intentionally across different areas of your life.

<Note>
  Priority zone assignments are a planning and reflection tool. They do **not** influence how completions are counted or how stats are calculated. A block completed in the Flexible zone counts exactly the same as one in the Main Focus zone. Use the Priority Circle to guide where you invest your time, then let the heatmap show you whether your actual behavior matches your intentions.
</Note>

## Reading Your Stats Together

<Accordion title="How to interpret your numbers as a system">
  The three metrics work best when you read them together rather than in isolation:

  * A **high completion rate** with a **short streak** suggests you schedule well on the days you show up but struggle with consistency.
  * A **long streak** with a **low completion rate** suggests you are maintaining the habit of showing up but may be over-scheduling or leaving blocks incomplete.
  * A **dense heatmap** with a **low total\_minutes** suggests many short sessions — consider whether longer, focused blocks would serve you better.

  Aim for steady improvement across all three rather than optimizing any one metric at the expense of the others.
</Accordion>