A subnet life's website status and domain registration warnings
https://api.bittensor.ai/api/v2/subnets/{netuid}/web-presence- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Whether the subnet's website answers and how.
Full description
Whether the subnet's website answers and how (website: status up / redirect_offsite / down / error / robots_disallowed, the HTTP status, the URL after redirects, the redirect count, the page title, TLS validity and expiry, when the state began), and its domain's registration warnings (domain: registered_after_life_start, expires_within_30d, registrar_changed, with the registry's dates). Observed by bittensor.ai's off-chain checks of the links the life's on-chain identity names (each figure with its as_of); the page's content is never served. The website is the identity's URL field while it names one, else another link it names; the domain is that link's registrable domain. A figure that cannot be stated is null with its *_reason (never 0 or false); website / domain are null with website_reason / domain_reason when nothing was checked. Links: url and final_url are plain text; link is set only when the URL was assessed safe (display link), and URLs assessed malicious are not served. Life: the slot's current life (the head subnet directory's generation), or the one generation names (an ended subnet's own page). Everything is keyed by the life: a re-registered slot never shows the previous subnet's website. Cached 5 minutes (slow class), an ended life's answer 1 hour. Errors are application/problem+json: INVALID_NETUID, SUBNET_NOT_FOUND (404: no subnet is registered in the slot at the head; with generation, the slot was never registered), INVALID_GENERATION (400), GENERATION_NOT_FOUND (404: the slot never had that life), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SERVICE_UNAVAILABLE (503), SOURCE_NOT_READY (503: web presence is not served on this deployment yet).
Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).
Path parameters
- netuidpath, required· integer · 0 to 65535
Subnet slot (0 = root).
Query parameters
- generationquery· integer · at least 0
The subnet life to serve: its
generationasGET /api/v2/subnets/generationsnames it, or itsstart_height; the id is matched first, anddata.generation/meta.generationis always the canonical id. Omitted: the slot's current life. Neither of a life of the slot: a 404GENERATION_NOT_FOUND; not an integer >= 0: a 400INVALID_GENERATION.
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 life, its website and its domain.
- netuidinteger · unit id
Subnet slot (0 = root).
- generationinteger · unit id · can be null
Opaque life id (the life's registration identifier), NOT a block height; use
life_start_heightfor the first block. The subnet life served: the slot's current life, or the one thegenerationparameter names (always its canonical id). Null when no life is recorded for the slot (nothing is then read).- life_start_heightinteger · unit block · can be null
The first block of the life
generationnames (GET /subnets/generations'start_height): use it, nevergeneration, for heights, ages and dates. Null exactly whengenerationis null (root without a life, no subnet), or transiently when this API cannot read the lives. Root'sgeneration0 starts at 0.- is_current_lifeboolean · can be null
Whether
generationis the slot's current life (true) or an ended one, re-registered since (false). Null exactly whengenerationis null, or transiently when this API cannot read the lives. Root'sgeneration0 is current.- websiteobject · can be null
The latest check of the life's website: the identity's URL field while it names one, else another link it names. Null with
website_reason.20 fields in website
- urlstring
The link checked, in canonical form, as the identity names it. Plain text: it is a link only through
link.- linkstring · can be null
urlwhen it may be rendered as a clickable link (displaylink: assessed safe); null otherwise, andurlis then shown as text only.- displaystring
How to render
url:link(assessed safe:linkis set),text(not assessed yet: plain text),text_warning(assessed suspicious: plain text with a warning). URLs assessed malicious are not served. New values may be added; show an unknown value as is (or generically).- verdictstring
The URL's safety assessment:
safe,suspicious, orunknown(not assessed yet). New values may be added; show an unknown value as is (or generically).- kindstring
Which identity field names the link:
website(the identity's URL field), else that field's name. New values may be added; show an unknown value as is (or generically).- in_identityboolean
Whether the life's identity still names the link (false once it no longer does).
- statusstring
The page's state at the last check:
up(a 2xx answer on the same site),redirect_offsite(a 2xx answer after a redirect to another domain),down(no answer, or a 4xx / 5xx),error(the check refused to follow: a private address, too many redirects, ...),robots_disallowed(the site's robots rules forbid the check; not fetched). New values may be added; show an unknown value as is (or generically).- http_statusinteger · unit id · can be null
The final HTTP status code. Null when there was no response (see
status).- final_urlstring · can be null
The URL after redirects. Not assessed for safety: plain text, never a link. Null when there was no response.
- redirect_countinteger · unit count · can be null
Redirects followed. Null when there was no response.
- content_typestring · can be null
The final response's media type (
text/html, ...). Null when not stated.- titlestring · can be null
The page title, at most 300 characters. Untrusted text: render escaped, never as a link. Null when the page has none.
- tls_okboolean · can be null
true: the certificate verified; false: the TLS connection failed. Null with
tls_reason.- tls_reasonstring · can be null
Why
tls_okis null; null when it is set:not_https(the link is not HTTPS),no_response(nothing answered),not_fetched(the site's robots rules forbid the check),not_reported(the check did not report it). New values may be added; treat unknown values as unavailable.- tls_expires_atstring (date-time) · can be null
When the certificate expires, RFC 3339 UTC. Null when there was no certificate.
- Format: date and time, ISO 8601 in UTC
- error_classstring · can be null
Why the check failed, when it did:
dns,connect,timeout,tls,protocol, or a class of refusal. Null when it did not fail. New values may be added; show an unknown value as is (or generically).- status_sincestring (date-time)
When the current state (status, HTTP status, final URL, title, content) was first observed, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- content_changed_atstring (date-time) · can be null
The last observed change of the page's content, RFC 3339 UTC. Null when none was seen.
- Format: date and time, ISO 8601 in UTC
- first_seen_atstring (date-time)
The link's first check, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- as_ofstring (date-time) · can be null
The last check, RFC 3339 UTC: every figure in this object is as of it. Null when the time of the check is not recorded.
- Format: date and time, ISO 8601 in UTC
- website_reasonstring · can be null
Why
websiteis null; null when it is served:not_checked(the identity names no website, or it has not been checked yet). New values may be added; treat unknown values as unavailable.- domainobject · can be null
The registration warnings of the website's domain (of the same identity field; the domain the identity names now first). Null with
domain_reason.17 fields in domain
- domainstring
The registrable domain of the website link (
example.com).- kindstring
Which identity field names the domain's link:
website(the identity's URL field), else that field's name. New values may be added; show an unknown value as is (or generically).- is_currentboolean
Whether the life's identity still names the domain.
- first_seen_atstring (date-time)
When the identity was first seen naming it, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- registration_statusstring
registered,not_registered,registry_not_queryable(the domain's registry offers no public lookup),unknown(the lookup gave no definitive answer),not_checked(not looked up yet). New values may be added; show an unknown value as is (or generically).- registered_after_life_startboolean · can be null
true: the domain's registration date is later than the life's start (registered again, or taken over, after the subnet named it). Null with
registered_after_life_start_reason.- registered_after_life_start_reasonstring · can be null
Why
registered_after_life_startis null; null when it is set:not_checked,not_registered,registry_not_queryable,unknown,no_registration_date(the registry states none),not_computed. Known values:not_checked,not_registered,registry_not_queryable,unknown,no_registration_date,no_expiry_date,not_computed. New values may be added; treat unknown values as unavailable.- registered_atstring (date-time) · can be null
The registration date the registry states, RFC 3339 UTC. Null when it states none.
- Format: date and time, ISO 8601 in UTC
- expires_within_30dboolean · can be null
true: the registration expires within 30 days of
as_of, or has expired. Null withexpires_within_30d_reason.- expires_within_30d_reasonstring · can be null
Why
expires_within_30dis null; null when it is set:not_checked,not_registered,registry_not_queryable,unknown,no_expiry_date(the registry states none). Known values:not_checked,not_registered,registry_not_queryable,unknown,no_registration_date,no_expiry_date,not_computed. New values may be added; treat unknown values as unavailable.- expires_atstring (date-time) · can be null
The expiry date the registry states, RFC 3339 UTC. Null when it states none.
- Format: date and time, ISO 8601 in UTC
- registrar_changedboolean · can be null
true: the domain's latest registration change moved it to another registrar. Null with
registrar_changed_reason.- registrar_changed_reasonstring · can be null
Why
registrar_changedis null; null when it is set:not_checked,not_registered,registry_not_queryable,unknown. Known values:not_checked,not_registered,registry_not_queryable,unknown,no_registration_date,no_expiry_date,not_computed. New values may be added; treat unknown values as unavailable.- registrar_changed_atstring (date-time) · can be null
When the registrar change was observed, RFC 3339 UTC. Null when none was.
- Format: date and time, ISO 8601 in UTC
- registry_changed_atstring (date-time) · can be null
The registry's own last-changed date for the domain, RFC 3339 UTC. Null when not stated.
- Format: date and time, ISO 8601 in UTC
- as_ofstring (date-time) · can be null
The last definitive registry answer, RFC 3339 UTC: the flags and dates are as of it. Null before the first.
- Format: date and time, ISO 8601 in UTC
- checked_atstring (date-time) · can be null
The last lookup attempt, RFC 3339 UTC (later than
as_ofwhen it failed). Null before the first.- Format: date and time, ISO 8601 in UTC
- domain_reasonstring · can be null
Why
domainis null; null when it is served:not_checked(no domain looked up for the life yet). New values may be added; treat unknown values as unavailable.
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
- GENERATION_NOT_FOUND
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_GENERATION
- INVALID_NETUID
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- SUBNET_NOT_FOUND
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.