Skip to content
TAO$188.12
BTC0.002928
MCap$2.21B
Vol$86.07M

API reference / Runtimes and storage

One runtime's metadata (JSON hex or raw SCALE)

GET/api/v2/runtimes/{spec_version}/metadata
Status
Stable
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

One runtime's metadata: what Metadata_metadata_at_version(version) returns for that spec, SCALE RuntimeMetadataPrefixed (it starts with meta, 0x6d657461, then the version byte). version picks the metadata version (the runtime's metadata_versions in GET /api/v2/runtimes: 14, 15 and 16 for current runtimes, 14 alone for old ones); without it, the highest the runtime offers. format=json (the default) answers {data, meta} with the bytes as 0x hex, their length and sha256 and the block they were read at; format=scale answers the raw bytes as application/octet-stream (about half the size), with the spec, the metadata version and the block hash in the X-Runtime-Spec-Version, X-Metadata-Version and X-Block-Hash headers. Metadata never changes for a spec and version, so both formats are cached as settled with a strong ETag from metadata_sha256 and the version (If-None-Match answers 304); the JSON form's meta.at is that of when it was computed. Large: about 400 KB for a current runtime (800 KB as hex). Errors are application/problem+json in both formats: INVALID_SPEC_VERSION, INVALID_VERSION, INVALID_FORMAT, RUNTIME_NOT_FOUND (404, no such spec), VERSION_NOT_OFFERED (400; the problem carries the extension member offered, the versions this runtime does offer), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Path parameters

spec_versionpath, required· integer · 0 to 2147483647

The runtime's spec_version (e.g. 470).

Query parameters

versionquery· integer · 0 to 255

The metadata version (14, 15 or 16 today; the runtime's metadata_versions). Default: the highest the runtime offers. One it does not offer is a 400 VERSION_NOT_OFFERED carrying offered.

formatquery· enum · one of json, scale · default json

json (the default): {data, meta} with the metadata as 0x hex. scale: the raw bytes, application/octet-stream.

Response

data is an object with these fields. Amounts are integer strings in their base unit, and null means unknown, never zero (see Units and formats). meta.at names the block the answer was read at.

The metadata and what it is.

spec_versioninteger · unit id

The runtime's spec_version.

versioninteger · unit id

The metadata version (14, 15, 16): the one asked for, else the highest the runtime offers.

block_hashstring

The block whose state the metadata was read at (any block running this spec), 0x + 64 hex.

Format: 32-byte hex: 0x and 64 hex digits
size_bytesinteger · unit count

Length of the metadata in bytes (not of its hex).

metadata_sha256string

sha256 of the metadata bytes, 64 lower-case hex. Fixed per spec and version: the response's ETag is computed from it.

Pattern: ^[0-9a-f]{64}$
metadatastring

The runtime's Metadata_metadata_at_version(version) result, SCALE RuntimeMetadataPrefixed (it starts with meta, 0x6d657461, then the version byte), as 0x hex. format=scale serves the same bytes raw.

Pattern: ^0x([0-9a-f]{2})+$

Response headers

13 headers: X-Runtime-Spec-Version, X-Metadata-Version, X-Block-Hash, ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
X-Runtime-Spec-Version

With format=scale: the runtime's spec_version.

X-Metadata-Version

With format=scale: the metadata version of the bytes (14, 15, 16).

X-Block-Hash

With format=scale: the block whose state the metadata was read at, 0x + 64 hex.

ETag

Strong validator of this answer. Send it back as If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.

Cache-Control

One of three classes: settled public, max-age=3600, stale-while-revalidate=86400 (pinned to a block that cannot move), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, max-age=6, stale-while-revalidate=12 (follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Never immutable. no-store on an earlier answer served because the data source failed (X-BTAI-Stale).

CDN-Cache-Control

The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with stale-while-revalidate and stale-if-error; no-store with X-BTAI-Stale.

X-BTAI-Stale

Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then if-error, with X-BTAI-Stale-As-Of, Age (its seconds since then) and Warning: 110 - "Response is Stale", and Cache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.

X-BTAI-Stale-As-Of

With X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).

RateLimit-Policy

The tier's request quota of the current window (IETF draft), e.g. "tier";q=600.

RateLimit

Requests left in the current window and the seconds until it resets (IETF draft), e.g. "tier";r=597;t=42.

X-RateLimit-Limit

The tier's request quota of the current window.

X-RateLimit-Remaining

Requests left in the current window.

X-RateLimit-Reset

When the current window resets, Unix seconds.

Status codes

200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

304 Not Modified: the If-None-Match validator still matches; no body.

Error codes

The codes this endpoint can return. Each links to what it means and what to do.

From the API's published specification, version 1.165.0.