> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloklake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response metadata

> The range a response covers, where to continue, the chain head and finality.

Every response describes itself. In Arrow, the values are strings in each stream's schema
metadata under `bl.*` keys (the same on every stream). In JSON, they are top-level fields of the
body.

| Arrow key | JSON field | Meaning |
| - | - | - |
| `bl.row_type` | — | this stream's row type: `transactions`, `logs` or `blocks` |
| `bl.streams` | — | every stream of the response, in order: `"transactions,logs,blocks"` |
| `bl.from_block` | `from_block` | the first block this response covers |
| `bl.to_block` | `to_block` | the last block this response covers (after clamping to the head and pagination) |
| `bl.next_block` | `next_block` | the `fromBlock` for the next page |
| `bl.objects` | `objects` | how many rows (blocks + transactions + logs) this response carries |
| `bl.archive_height` | `archive_height` | the chain head at query time: the newest block you can query |
| `bl.finalized_block` | `finalized_block` | the newest final block at query time; rows at or below it never change |
| `bl.to_block_hash` | `to_block_hash` | the hash of `to_block`, only when `to_block` is above `finalized_block` (`null` / absent otherwise) |
| `bl.query_id_template` | `query_id_template` | the [prepared query](https://docs.bloklake.com/querying/prepared-queries.md) id of this request's filter |
| `bl.unavailable_fields` | `unavailable_fields` | selected fields this chain doesn't have: comma-separated in Arrow (`""` = none), a list in JSON |

## Reading it

```python pyarrow theme={null}
meta = {k.decode(): v.decode() for k, v in reader.schema.metadata.items()}
next_block = int(meta["bl.next_block"])
```

```typescript arrow-js theme={null}
const meta = reader.schema.metadata;          // Map<string, string>
const nextBlock = Number(meta.get("bl.next_block"));
```

```rust arrow-rs theme={null}
let meta = reader.schema().metadata().clone(); // HashMap<String, String>
let next_block: u64 = meta["bl.next_block"].parse()?;
```

## How to use each value

* **`next_block`** drives the [pagination loop](https://docs.bloklake.com/querying/pagination.md). Continue while it's at or
  below the end of your range.
* **`from_block` / `to_block`** are what you actually got. Near the head, `to_block` is lower
  than the `toBlock` you asked for. Past the head, a response has no rows, `to_block` equals the
  head and `next_block` equals your `fromBlock`.
* **`objects`** is the row count to check against what you decoded, to catch a truncated body;
  see [Reading Arrow](https://docs.bloklake.com/responses/reading-arrow.md).
* **`finalized_block` / `to_block_hash`** tell you which rows are final and let you detect reorgs;
  see [Finality and reorgs](https://docs.bloklake.com/querying/finality-and-reorgs.md).
* **`archive_height`** is useful to decide when an open-ended backfill has caught up, and to
  measure how far behind your own pipeline is.

> [!NOTE]
>
> There is no "truncated" or "has more" flag. `next_block` compared with the end you want is the
> whole story.

## Request ids

Every response has an `X-Request-Id` header: the value you sent in a header of the same name (up
to 128 printable characters), or one the server generated. Log it with your errors and quote it
when you contact support; it identifies the request in our logs.

```bash theme={null}
curl -i https://api.bloklake.com/v1/chains/eth/query/json -H "X-Request-Id: backfill-42-page-17" …
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.