---
title: "Historical callTracer trace tree for one transaction"
method: GET
path: "/{chain}/transactions/{hash}/trace"
tags: ["Traces"]
---

# Historical callTracer trace tree for one transaction

`GET /{chain}/transactions/{hash}/trace`

## Request

- Base URL: `https://api.blockvectra.com/v1/data`
- URL: `https://api.blockvectra.com/v1/data/{chain}/transactions/{hash}/trace`
- Auth: API key in header `x-api-key`

Reconstructed `callTracer` call frame for a single transaction by its transaction hash. Unpaginated; `next_cursor` is never present. `data` is the call frame object directly.

## Path parameters

- `chain` string, required
- `hash` string, required: 32-byte hash. `0x`/`0X` prefix optional; either hex digit case is accepted.

## Response `200`

This transaction's call tree.

- TxTraceEnvelope: Unpaginated; `next_cursor` is never present.
  - `data` 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"`: `{hash}` does not parse as a 32-byte hash (`0x` optional, either case).
- `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 no transaction with this `{hash}` exists in the lookup table (a transaction submitted moments ago may take a few seconds to be indexed; `message` says so -- retry briefly before treating it as permanent), or it resolved to a block whose trace tree has no matching transaction. If the hash is found in the lookup table but resolves to a block above `as_of_block`, it returns `409 not_indexed_yet` instead.
- `409`: `error.code = "not_indexed_yet"`: the resolved block is above `as_of_block`. On a chain with no indexed block at all it is the same code without `indexed_through` (see "Errors").
- `422`: `error.code = "no_coverage"`: the chain does not have the `traces` capability (checked first), or the resolved block falls in a permanent trace coverage gap -- the chain has no trace data at all yet (`coverage.traces_from_block` is `null`), the block 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) the resolved block 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)