Retrieve Study Stats and Heatmap — Take Time API

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

GET /v1/stats

Query Parameters

string

default:"week"

The time window to aggregate stats over. Accepted values: today, week, month, all.

Response Fields

number

Total number of scheduled study blocks in the requested period.

number

Number of blocks that have been marked as completed within the period.

number

Ratio of completed blocks to total blocks, expressed as a decimal between 0 and 1.

number

Your current consecutive-day completion streak. Resets if you miss a day entirely.

number

Total study time accumulated across all completed blocks in the period, in minutes.

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.

Example Response

{
  "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

curl https://api.taketime.app/v1/stats?period=month \
  -H "Authorization: Bearer tt_live_your_key_here"

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`);
}

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

Overview

Blocks

Subjects

Stats & Schedule

Retrieve Study Stats and Heatmap — Take Time API

Endpoint

Query Parameters

Response Fields

Example Response

Code Examples

​Endpoint

​Query Parameters

​Response Fields

​Example Response

​Code Examples

Endpoint

Query Parameters

Response Fields

Example Response

Code Examples