API reference / Runtimes and storage
One runtime's metadata (JSON hex or raw SCALE)
https://api.bittensor.ai/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 400VERSION_NOT_OFFEREDcarryingoffered.- 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, SCALERuntimeMetadataPrefixed(it starts withmeta, 0x6d657461, then the version byte), as 0x hex.format=scaleserves 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), slowpublic, max-age=300, stale-while-revalidate=600(state that moves in minutes or days) or tippublic, 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). Neverimmutable.no-storeon 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-revalidateandstale-if-error;no-storewithX-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, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_FORMAT
- INVALID_SPEC_VERSION
- INVALID_VERSION
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- RUNTIME_NOT_FOUND
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
- VERSION_NOT_OFFERED
From the API's published specification, version 1.165.0.