Search results across blocks, extrinsics, accounts, subnets, validators, EVM and runtime, paged
https://api.bittensor.ai/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 400QUERY_TOO_SHORT, longer anINVALID_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 400INVALID_TYPES.evm_tx(an EVM transaction hash) is a 503SOURCE_NOT_READYwhile 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_cursorof 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 400INVALID_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 atGET /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 inaddress;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, avalidatoror afund: the account as{ss58, hex}(the hex isid). 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 saysverified.- 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_reasonsays why.- 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τensorforopentensor),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
routewith 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), 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_CURSOR
- INVALID_LIMIT
- INVALID_QUERY
- INVALID_TYPES
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- QUERY_TOO_SHORT
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.