Response metadata

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

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

const meta = reader.schema.metadata;          // Map<string, string>
const nextBlock = Number(meta.get("bl.next_block"));

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. 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.
finalized_block / to_block_hash tell you which rows are final and let you detect reorgs; see Finality and reorgs.
archive_height is useful to decide when an open-ended backfill has caught up, and to measure how far behind your own pipeline is.

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.

curl -i https://api.bloklake.com/v1/chains/eth/query/json -H "X-Request-Id: backfill-42-page-17" …

Get started

Chains

Querying

Responses

Guides

Account

Billing

Production

Response metadata

Reading it

How to use each value

Request ids

​Reading it

​How to use each value

​Request ids

Reading it

How to use each value

Request ids