List Study Blocks — GET /blocks Endpoint Reference

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

string

Filter blocks by an exact date. Must be in YYYY-MM-DD format. Cannot be combined with date_from or date_to.

string

Start of a date range filter. Must be in YYYY-MM-DD format. Use together with date_to to define a range.

string

End of a date range filter. Must be in YYYY-MM-DD format. Use together with date_from to define a range.

string

Filter blocks by a specific subject. Only blocks belonging to the given subject ID are returned.

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.

string

Unique identifier for the study block.

string

The ID of the subject this block belongs to.

string

The display name of the subject.

string

The date of the block in YYYY-MM-DD format.

string

The block’s start time in HH:MM format.

string

The block’s end time in HH:MM format.

string

An optional topic or syllabus item label attached to this block. May be null.

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"

const response = await fetch(
  'https://api.taketime.app/v1/blocks?date_from=2026-06-11&date_to=2026-06-17&done=false',
  {
    headers: {
      'Authorization': 'Bearer tt_live_your_key_here',
    },
  }
);

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

if (error) {
  console.error('Error:', error.code, error.message);
} else {
  console.log(`Retrieved ${data.length} blocks`);
}

To fetch blocks for a single day, use the date parameter rather than setting date_from and date_to to the same value.

Overview

Blocks

Subjects

Stats & Schedule

List Study Blocks — GET /blocks Endpoint Reference

Endpoint

Query Parameters

Response

Examples

​Endpoint

​Query Parameters

​Response

​Examples

Endpoint

Query Parameters

Response

Examples