Skip to content
TAO$188.40
BTC0.00293
MCap$2.21B
Vol$86.07M

API reference / Identities

Search on-chain identities

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

Accounts whose current on-chain identity (SubtensorModule IdentitiesV2) matches q, ignoring case, best match first: exact (the name equals q), prefix (the name starts with it), contains (the name contains it), other_field (only the URL, GitHub repository or Discord handle contains it); then shorter names first. Each row is {address: {ss58, hex}, match, identity}, the identity as /accounts/identities serves it. At most limit rows (default 20, at most 50), no paging: narrow the query for more. A past identity is not searched (/accounts/{address}/identity/history has them). Always the head, so tip-cached. Errors are application/problem+json: QUERY_TOO_SHORT (q missing, or under 2 characters once spaces are trimmed), INVALID_QUERY (over 100), INVALID_LIMIT, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Query parameters

qquery· string

The text to look for, 2..100 characters (leading and trailing spaces ignored; matched ignoring case, % and _ literally).

limitquery· integer · default 20 · 1 to 50

At most this many rows, 1..50 (default 20; this route's cap, above it is a 400 INVALID_LIMIT).

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.

At most limit rows, by match (exact, prefix, contains, other field), then the shorter name, then the name. [] when nothing matches.

addressobject

The account, as {ss58, hex}.

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
matchenum

How it matched, best first (the rows come in this order): exact (the name equals the query, ignoring case), prefix (the name starts with it), contains (the name contains it), other_field (the URL, GitHub repository or Discord handle contains it, the name does not).

One of: exact, prefix, contains, other_field
identityobject

Its on-chain identity now (SubtensorModule IdentitiesV2).

9 fields in identity
namestring · can be null

The display name. As the owner set it (UTF-8; "" when left empty); null when the stored bytes are not valid UTF-8 (decoded false).

urlstring · can be null

The website. As the owner set it (UTF-8; "" when left empty); null when the stored bytes are not valid UTF-8 (decoded false).

github_repostring · can be null

The GitHub repository. As the owner set it (UTF-8; "" when left empty); null when the stored bytes are not valid UTF-8 (decoded false).

imagestring · can be null

The identity's image: 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: image_unavailable_reason says why.

discordstring · can be null

The Discord handle. As the owner set it (UTF-8; "" when left empty); null when the stored bytes are not valid UTF-8 (decoded false).

descriptionstring · can be null

A free-text description. As the owner set it (UTF-8; "" when left empty); null when the stored bytes are not valid UTF-8 (decoded false).

additionalstring · can be null

Any additional text. As the owner set it (UTF-8; "" when left empty); null when the stored bytes are not valid UTF-8 (decoded false).

image_unavailable_reasonstring · can be null

Why image 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 image is served. New values may be added; treat unknown values as unavailable.

decodedboolean

True when every stored field is valid UTF-8; false when one is not (that field is then null).

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.