Skip to content
TAO$188.21
BTC0.002927
MCap$2.22B
Vol$86.25M

API reference / Search

Search results across blocks, extrinsics, accounts, subnets, validators, EVM and runtime, paged

GET/api/v2/search
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

The search results page: limit rows per page (default 20, at most 100), best first, keyset-paged by meta.page.next_cursor (bound to q, types and limit).

Full description

The search results page: limit rows per page (default 20, at most 100), best first, keyset-paged by meta.page.next_cursor (bound to q, types and limit). Each row is {type, id, address, title, subtitle, icon_url, score, matched_field, kind, match, target}: id is the entity's v2 id (the form its route takes); an account, validator or fund also carries address = {ss58, hex}; kind groups the row (account, identity, validator, subnet, block, extrinsic, evm_tx, contract, token, runtime, ...); match says how the query met it (exact, prefix, normalized, partial); target is the detail route to link ({route, params}). Exact identifiers are resolved first and verified to exist (matched_field id): a 32-byte hex is tried as an extrinsic, block and EVM transaction hash, an H160 as an EVM address, contract and its mapped account, an SS58 under any network prefix as the account (meta.recognized). Then names, symbols, aliases and labels from the name index (meta.index_updated_at): exact > prefix > fuzzy, then the row type, then popularity; among those, rows whose match is exact come first, then prefix. A lookup that cannot answer in time is named in meta.unavailable and only its rows are missing. score is relative only: it ranks one answer's rows and has no fixed scale. meta.redirect is the one exact identifier when exactly one matched (go straight to it); null when none did or the match is ambiguous (64 is block 64 and subnet 64). Identity names are self-asserted; labels annotate and never state where they came from; only a contract with source-verified code is called verified. Cached as tip (6 s). Errors are application/problem+json: QUERY_TOO_SHORT, INVALID_QUERY, INVALID_TYPES, INVALID_LIMIT, INVALID_CURSOR, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Query parameters

qquery· string

What to look for, 2..100 characters once leading and trailing spaces are trimmed: a block height or hash, an extrinsic or event id (h-i), a call id (h-i.c), an account (SS58 under any network prefix, or its 0x public key), an EVM address (its mapped account is found too) or transaction hash, a subnet (12, sn12, its name or token symbol), a validator, fund, exchange, token, contract or precompile name, a runtime call or event (SubtensorModule.add_stake). Names match ignoring case and accents, by prefix and fuzzily. Missing or shorter is a 400 QUERY_TOO_SHORT, longer an INVALID_QUERY.

typesquery· string

Only these row types (comma list or repeated): block, extrinsic, event, call, account, evm_address, subnet, subnet_life, validator, fund, entity, evm_contract, evm_token, precompile, runtime_call, runtime_event, evm_tx. Default: every type. Anything else (or an empty entry) is a 400 INVALID_TYPES. evm_tx (an EVM transaction hash) is a 503 SOURCE_NOT_READY while the data source does not serve it yet.

limitquery· integer · default 20 · 1 to 100

Page size, 1..100 (default 20). Anything else is a 400 INVALID_LIMIT.

cursorquery· string · up to 200 characters

meta.page.next_cursor of the previous page, passed back unchanged with the same other parameters. It is opaque and bound to them: a cursor used with different parameters, or altered, is a 400 INVALID_CURSOR.

Response

data is a list of objects 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 results, best first: exact identifiers first, then name matches with match exact before prefix before the rest, each group by rank. [] when nothing matched.

typestring

What the row is: block, extrinsic, event, call, account, evm_address (any H160: not checked to exist), subnet, subnet_life, validator, fund, entity (an exchange), evm_contract (a contract with source-verified code), evm_token, precompile, runtime_call, runtime_event, evm_tx (an EVM transaction matched by its 0x + 64 hex hash, always an exact match; open it at GET /api/v2/evm/transactions/{tx_hash}. One row per hash: a hash several transactions share is one row, its subtitle naming the newest one's block and how many share it, and the detail serves the newest). A closed set. New values may be added; show an unknown value as is (or generically).

idstring

The entity's v2 id, the form the matching v2 route takes in its path: a height (block), h-i (extrinsic, event), h-i.c (call), 0x + 64 lower-case hex (account, validator, fund: the account, also in address; evm_tx: the EVM transaction hash), 0x + 40 lower-case hex (evm_address, evm_contract, evm_token, precompile), a netuid (subnet), netuid:life (subnet_life), Pallet.name (runtime_call, runtime_event), an entity id (entity).

addressobject · can be null

For an account, a validator or a fund: the account as {ss58, hex} (the hex is id). Null for every other type.

2 fields in address
ss58string

The account, SS58 (prefix 42).

Format: SS58 address
hexstring

The same 32-byte account id, 0x + 64 lower-case hex (the public key).

Format: 32-byte hex: 0x and 64 hex digits
titlestring

What to show: the subnet's or validator's name, the account's on-chain identity name or its label, Block #h, ... Identity names are self-asserted by their owners; labels are attributions, never chain facts.

subtitlestring · can be null

One line of context (Subnet 12 · SYM, Validator · 1234 τ stake, EVM contract · verified source, ...). A label annotates and never states where it came from. Only a contract whose source is verified says verified.

icon_urlstring · can be null

An image for the row (a subnet's logo): our copy of the image (fetched, checked and re-encoded by bittensor.ai), never the URL set on chain. Null when we hold no copy: icon_url_unavailable_reason says why.

icon_url_unavailable_reasonstring · can be null

Why icon_url is null: none_set (no image is set on chain), not_mirrored_yet (one is set and we hold no copy of it yet), fetch_failed (our last fetch of it failed: not found, refused, unreachable, or not a usable https URL) or unsafe_content (what it points at was refused: not an allowed image type, invalid or too large). Null exactly when icon_url is served. New values may be added; treat unknown values as unavailable.

scorestring · unit score · 3 decimals

The rank score, a decimal string (3 decimals). Relative only: it ranks the rows of one answer (an exact identifier > an exact name / symbol > a prefix > a fuzzy match, then the type, then a popularity tiebreak) and has no fixed scale; never compare it across queries or show it as a percentage. The page order is the rank refined by match (below), so a score can rise down the page among name matches.

Format: decimal number, as a string
matched_fieldenum

What matched: id (an exact identifier, verified to exist; these rows lead the answer), name, symbol, alias (sn12, subnet 12, a pallet), label, netuid, address (an SS58 prefix of a validator or fund), owner_identity (a subnet matched on its CURRENT owner's identity name; a re-registered slot never carries the previous owner's). A closed set.

One of: id, name, symbol, alias, label, netuid, address, owner_identity
kindstring

What the row is, coarser than type, for an icon or a group heading: block, extrinsic, event, call, account (an account or an EVM address), identity (an account found by its on-chain identity name), subnet (a subnet or one of its lives), validator, fund, entity, contract (an EVM contract or a precompile), token, runtime (a runtime call or event), evm_tx. A row type this list does not know yet is served as its own kind. New values may be added; show an unknown value as is (or generically).

matchstring

How the query met the row, for display only (it makes no statement about the row): exact (an exact identifier, or the title or a subtitle part equals the query ignoring case), prefix (one starts with the query, ignoring case; an SS58 prefix of the row's account), normalized (equal or a prefix only once accents, look-alike letters, spaces and punctuation are disregarded: Openτensor for opentensor), partial (contained, a fuzzy match, or a field the row does not show). New values may be added; show an unknown value as is (or generically).

targetobject · can be null

The detail route this row opens ({route, params}), for linking a suggestion. Null for a row with no single detail route (runtime_call, runtime_event) and for a row type this API does not know yet.

2 fields in target
routestring

The v2 route's path template, e.g. /api/v2/blocks/{block}, /api/v2/accounts/{address}, /api/v2/subnets/{netuid}/generations/{generation}. Stable per row type.

paramsobject

The template's path parameters, as strings (an account as SS58, an EVM address or hash as 0x hex, a height or netuid as digits). Filling route with them gives the detail route's path.

Response headers

10 headers: 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
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.