> ## 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.

# Retrieve Study Stats and Heatmap — Take Time API

> Retrieve your Take Time stats including completion counts, streak days, total study minutes, and a per-day heatmap for any supported time period.

Use `GET /v1/stats` to pull your study progress data. The endpoint returns completion metrics, your current streak, total minutes studied, and a per-day heatmap that powers the activity grid in the app.

## Endpoint

```http theme={null}
GET /v1/stats
```

## Query Parameters

<ParamField query="period" type="string" default="week">
  The time window to aggregate stats over. Accepted values: `today`, `week`, `month`, `all`.
</ParamField>

## Response Fields

<ResponseField name="total_blocks" type="number">
  Total number of scheduled study blocks in the requested period.
</ResponseField>

<ResponseField name="completed_blocks" type="number">
  Number of blocks that have been marked as completed within the period.
</ResponseField>

<ResponseField name="completion_rate" type="number">
  Ratio of completed blocks to total blocks, expressed as a decimal between `0` and `1`.
</ResponseField>

<ResponseField name="streak_days" type="number">
  Your current consecutive-day completion streak. Resets if you miss a day entirely.
</ResponseField>

<ResponseField name="total_minutes" type="number">
  Total study time accumulated across all completed blocks in the period, in minutes.
</ResponseField>

<ResponseField name="heatmap" type="object">
  A map of calendar dates to integer completion counts. Keys are ISO 8601 dates in `YYYY-MM-DD` format; values are the number of blocks completed on that day.
</ResponseField>

## Example Response

```json theme={null}
{
  "data": {
    "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
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}
```

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.taketime.app/v1/stats?period=month \
    -H "Authorization: Bearer tt_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.taketime.app/v1/stats?period=month",
    {
      headers: {
        Authorization: "Bearer tt_live_your_key_here",
      },
    }
  );

  const { data, error } = await response.json();

  if (error) {
    console.error("Failed to fetch stats:", error);
  } else {
    console.log(`Completion rate: ${(data.completion_rate * 100).toFixed(0)}%`);
    console.log(`Current streak: ${data.streak_days} days`);
    console.log(`Total study time: ${data.total_minutes} minutes`);
  }
  ```
</CodeGroup>

<Note>
  The `heatmap` object only includes dates that have at least one completed block. Days with zero completions are omitted from the map entirely.
</Note>