<!-- source: https://secondlayer.tools/docs/api-reference#list-blocks -->

## Canonical blocks

`GET /v1/index/blocks`

Canonical blocks, oldest first. The cursor is `<block_height>:0`. The window follows the ingest tip, so it can run ahead of the decoded `tip.block_height`.

### Filters

| Name | Type | Description |
| --- | --- | --- |
| `wait` | integer | Seconds (max 25) to hold the response open when there's nothing new past your cursor/from_height, instead of answering immediately. Returns early the moment new data commits, or at the timeout — either way you get a normal response, just later. Omit for the old poll-and-retry behavior. |

### Range and paging

| Name | Type | Description |
| --- | --- | --- |
| `limit` | integer · 1 to 1000 | Page size; capped at 1000. |
| `cursor` | string | `<block_height>:<event_index>` from a previous page's `next_cursor`. Resumes after it. |
| `from_cursor` | string | Same as `cursor`. Mutually exclusive with it and with `from_height`. |
| `from_height` | integer | First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip. |
| `to_height` | integer | Last block height to read, inclusive. |

### Returns

A cursor envelope; `blocks` holds `Block` objects.

### Responses

- `200` Cursor-paginated envelope
- `400` A parameter, filter, cursor or body field was refused; `code` says which
- `401` This bind requires the instance token, and it was missing or wrong
- `429` Rate limited; retry after `Retry-After` seconds

### Example

```bash
curl https://api.secondlayer.tools/v1/index/blocks \
  -H "Authorization: Bearer $SECONDLAYER_API_KEY"
```

```json
{
  "blocks": [
    {
      "cursor": "9048502:0",
      "block_height": 9048502,
      "block_hash": "0x2a20974330e301b65086d3cde9b0006c9b7471479ba9a3fc2ca72621479655cc",
      "parent_hash": "0x10606e958095ef9b964e3c3f2d9eb75bf8577fb8c09c24ee492b767f7504abea",
      "burn_block_height": 968276,
      "burn_block_hash": "0x000000000000000000019d25cd76d06a9eea796a906ac88300cd70fd70ccdb57",
      "index_block_hash": "0x990152a894e12288960c8b68e5790ad7994f9d261e9ad8adc13c72e76f914339",
      "block_time": "2026-09-23T13:14:42.000Z",
      "canonical": true
    }
  ],
  "next_cursor": "7960000:42",
  "tip": {
    "block_height": 9048690,
    "finalized_height": 9048457,
    "lag_seconds": 4,
    "source_block_height": 9048692
  }
}
```