Skip to main content
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

​
period
string
default:"week"
The time window to aggregate stats over. Accepted values: today, week, month, all.

​
Response Fields

​
total_blocks
number
Total number of scheduled study blocks in the requested period.
​
completed_blocks
number
Number of blocks that have been marked as completed within the period.
​
completion_rate
number
Ratio of completed blocks to total blocks, expressed as a decimal between 0 and 1.
​
streak_days
number
Your current consecutive-day completion streak. Resets if you miss a day entirely.
​
total_minutes
number
Total study time accumulated across all completed blocks in the period, in minutes.
​
heatmap
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"
The heatmap object only includes dates that have at least one completed block. Days with zero completions are omitted from the map entirely.