Skip to main content
Use GET /v1/blocks to retrieve your study blocks. You can filter by a specific date, a date range, a subject ID, or completion status. Without any filters, the endpoint returns all blocks.

​
Endpoint

GET https://api.taketime.app/v1/blocks

​
Query Parameters

​
date
string
Filter blocks by an exact date. Must be in YYYY-MM-DD format. Cannot be combined with date_from or date_to.
​
date_from
string
Start of a date range filter. Must be in YYYY-MM-DD format. Use together with date_to to define a range.
​
date_to
string
End of a date range filter. Must be in YYYY-MM-DD format. Use together with date_from to define a range.
​
subject_id
string
Filter blocks by a specific subject. Only blocks belonging to the given subject ID are returned.
​
done
boolean
Filter by completion status. Pass true to return only completed blocks, or false to return only incomplete blocks.

​
Response

Returns an array of block objects inside the data field.
​
id
string
Unique identifier for the study block.
​
subject_id
string
The ID of the subject this block belongs to.
​
subject_name
string
The display name of the subject.
​
date
string
The date of the block in YYYY-MM-DD format.
​
start
string
The block’s start time in HH:MM format.
​
end
string
The block’s end time in HH:MM format.
​
topic
string
An optional topic or syllabus item label attached to this block. May be null.
​
done
boolean
Whether the block has been marked as complete.
Example response 
{
  "data": [
    {
      "id": "blk_abc123",
      "subject_id": "sub_xyz",
      "subject_name": "JavaScript",
      "date": "2026-06-11",
      "start": "09:00",
      "end": "10:00",
      "topic": "Ch. 3 — Arrays",
      "done": false
    },
    {
      "id": "blk_def456",
      "subject_id": "sub_abc",
      "subject_name": "Morning Run",
      "date": "2026-06-11",
      "start": "07:00",
      "end": "07:45",
      "topic": null,
      "done": true
    }
  ],
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}

​
Examples

curl "https://api.taketime.app/v1/blocks?date_from=2026-06-11&date_to=2026-06-17&done=false" \
  -H "Authorization: Bearer tt_live_your_key_here"
To fetch blocks for a single day, use the date parameter rather than setting date_from and date_to to the same value.