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

# List Study Blocks — GET /blocks Endpoint Reference

> GET /v1/blocks — retrieve study blocks with optional filters for date, date range, subject, and completion status. Returns an array of block objects.

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

<ParamField query="date" type="string">
  Filter blocks by an exact date. Must be in `YYYY-MM-DD` format. Cannot be combined with `date_from` or `date_to`.
</ParamField>

<ParamField query="date_from" type="string">
  Start of a date range filter. Must be in `YYYY-MM-DD` format. Use together with `date_to` to define a range.
</ParamField>

<ParamField query="date_to" type="string">
  End of a date range filter. Must be in `YYYY-MM-DD` format. Use together with `date_from` to define a range.
</ParamField>

<ParamField query="subject_id" type="string">
  Filter blocks by a specific subject. Only blocks belonging to the given subject ID are returned.
</ParamField>

<ParamField query="done" type="boolean">
  Filter by completion status. Pass `true` to return only completed blocks, or `false` to return only incomplete blocks.
</ParamField>

## Response

Returns an array of block objects inside the `data` field.

<ResponseField name="id" type="string">
  Unique identifier for the study block.
</ResponseField>

<ResponseField name="subject_id" type="string">
  The ID of the subject this block belongs to.
</ResponseField>

<ResponseField name="subject_name" type="string">
  The display name of the subject.
</ResponseField>

<ResponseField name="date" type="string">
  The date of the block in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="start" type="string">
  The block's start time in `HH:MM` format.
</ResponseField>

<ResponseField name="end" type="string">
  The block's end time in `HH:MM` format.
</ResponseField>

<ResponseField name="topic" type="string">
  An optional topic or syllabus item label attached to this block. May be `null`.
</ResponseField>

<ResponseField name="done" type="boolean">
  Whether the block has been marked as complete.
</ResponseField>

**Example response**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript Node.js theme={null}
  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`);
  }
  ```
</CodeGroup>

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