---
title: "Historical callTracer trace tree for a whole block"
method: GET
path: "/{chain}/blocks/{number}/traces"
tags: ["Traces"]
---

# Historical callTracer trace tree for a whole block

`GET /{chain}/blocks/{number}/traces`

## Request

- Base URL: `https://api.blockvectra.com/v1/data`
- URL: `https://api.blockvectra.com/v1/data/{chain}/blocks/{number}/traces`
- Auth: API key in header `x-api-key`

Reconstructed call tree per transaction in a block using `callTracer`, wrapped in the standard response envelope. **Returns the whole block, unpaginated** (`next_cursor` is never present). A permanent coverage gap returns `422`, never an empty array; a recent block with transactions but no trace data yet returns `503` instead -- once it is further behind the indexed head than the chain's trace window, it is `422` too (see "Errors" above).

## Path parameters

- `chain` string, required
- `number` integer, required

## Response `200`

One call tree per transaction in the block, in `tx_index` order (`[]` for a real, finalized block that has zero transactions).

- BlockTracesEnvelope: Unpaginated; `next_cursor` is never present.
  - `data` BlockTraceItem[], required
    - `txHash` string, required: 32-byte hash/topic, canonical form always `0x` + 64 lowercase hex digits.
    - `result` CallFrame, required: A single `callTracer` call frame in standard Ethereum `callTracer` format; `value`/`gas`/`gasUsed` are `0x`-prefixed hex quantities. Any additional fields in the call frame are preserved (`additionalProperties: true`).
      - `type` string, required: e.g. `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2`, `SELFDESTRUCT`.
      - `from` string, required: 20-byte address, canonical form always `0x` + 40 lowercase hex digits.
      - `to` string: 20-byte address, canonical form always `0x` + 40 lowercase hex digits.
      - `value` string: `0x`-prefixed hexadecimal integer in standard Ethereum `callTracer` format; `value`/`gas`/`gasUsed` are `0x`-prefixed hex quantities.
      - `gas` string, required: `0x`-prefixed hexadecimal integer in standard Ethereum `callTracer` format; `value`/`gas`/`gasUsed` are `0x`-prefixed hex quantities.
      - `gasUsed` string, required: `0x`-prefixed hexadecimal integer in standard Ethereum `callTracer` format; `value`/`gas`/`gasUsed` are `0x`-prefixed hex quantities.
      - `input` string, required: Raw bytes of any length, `0x` + an even number of lowercase hex digits (`"0x"` alone for zero bytes).
      - `output` string: Raw bytes of any length, `0x` + an even number of lowercase hex digits (`"0x"` alone for zero bytes).
      - `error` string: Absent on a successful call.
      - `revertReason` string: Absent unless the call reverted with `Error(string)` data.
      - `calls` CallFrame[]: Nested sub-calls, in call order. Absent for a leaf frame.
  - `meta` Meta, required: Metadata present on every success response.
    - `chain` string, required: Chain identifier; the value of the `{chain}` path parameter.
    - `chain_slug` string, required: Canonical uppercase chain slug; `chain` is always its lowercase form.
    - `chain_external_id` string, required: CAIP-2 formatted external chain identifier (`eip155:{chain_id}`).
    - `as_of_block` integer, required: The newest fully written block (the `blocks` table's maximum height); the only serving bound for block-scoped endpoints. For snapshot endpoints (balances, holders, nfts, dex prices, stocks) it is the service's current indexed head, not the block height of the snapshot: read the snapshot time from `meta.refreshed_at`, and treat the data as stale when `refreshed_at` is `null`.
    - `safe_block` integer, nullable, required: A marker only: the node's consensus `safe` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, never below `finalized_block`, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description.
    - `finalized_block` integer, nullable, required: A marker only: the node's consensus `finalized` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description.
    - `coverage` 'full' | 'partial', required: `"partial"` appears only from `GET /{chain}/addresses/{address}/transactions` and `GET /{chain}/addresses/{address}/transfers`, when `clamp=true` narrowed the served window, and from those two, `GET /{chain}/tokens/{token}/transfers` and `GET /{chain}/dex/swaps` when the block window starts before the lower bound of the dataset the endpoint reads -- the chain's first indexed block, or higher while that dataset is still being backfilled (see Coverage in the API description and each endpoint's window description). Every other endpoint reports `"full"`.
    - `refreshed_at` string, date-time, required: `YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision.

## Other responses

- `400`: `error.code = "bad_request"`: `{number}` is not a valid non-negative integer.
- `401`: HTTP 401: a missing API key returns missing_api_key; an unknown, disabled, or revoked key returns the same invalid_api_key error envelope. error.code and error.data.reason contain the reason. Rejected requests are not billed.
- `402`: Payment required: the paid balance or the free grant is exhausted. The response body is `{"error":{"code":"insufficient_balance"}}`. Rejected requests are not billed.
- `404`: `error.code = "not_found"`: either `{chain}` is unknown or not public, or block `{number}` does not exist (never indexed, or removed by a reorg).
- `409`: After the operation passes its earlier routing, capability, parameter and permit checks and reaches the indexed-head check, `error.code = "not_indexed_yet"` when the requested block (a `{number}` path parameter, or the block a hash resolved to) is above `as_of_block`, the newest fully written block (see "Errors" above). It carries `indexed_through`, the highest indexed block. `meta.finalized_block` is a marker only and never rejects an indexed block. On a chain with no indexed block at all it is also `not_indexed_yet` but `indexed_through` is **absent** (block 0 is not indexed either).
- `422`: `error.code = "no_coverage"`: the chain does not have the `traces` capability (checked first), or `{number}` falls in a permanent trace coverage gap -- the chain has no trace data at all yet (`coverage.traces_from_block` is `null`), `{number}` is before trace coverage started (below the chain's `coverage.traces_from_block` in `GET /chains`), inside a recorded gap, or (distinct from the `503` case below) it has transactions but was never traced and is already too far behind the indexed head for that to still be a pending write. `message` names the chain and the reason.
- `429`: Rate limited. `{"error":{"code":"rate_limited"}}` when the key CU rate limit is exceeded (the response includes `Retry-After`) or the account call rate limit is exceeded (no `Retry-After`). `{"error":{"code":"cost_exceeds_burst"}}` when a single request exceeds the key burst capacity; split the request, retrying as sent never succeeds. Rejected requests are not billed.
- `503`: `error.code = "unavailable"`: the data store is unreachable or slow (including while the chain's trace coverage start cannot be determined), or (see "Errors" above) `{number}` is a recent block with transactions but no trace data yet -- always with `Retry-After`.

---

[API](https://skmtc.dev/blockvectra/apis/blockvectra-data-api.md) · [All operations](https://skmtc.dev/blockvectra/apis/blockvectra-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blockvectra/apis/blockvectra-data-api/revisions/c5b949e955b5?raw)