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

API reference / Subnets

Every subnet's recent changes, newest first

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

Every subnet life's changes that occurred in the last days days (meta.window: up to now, snapped up to the hour), newest first, keyset-paged through meta.page.next_cursor (the cursor carries the window, so every page reads the same one; a cursor whose window starts more than 31 days ago is refused).

Full description

Every subnet life's changes that occurred in the last days days (meta.window: up to now, snapped up to the hour), newest first, keyset-paged through meta.page.next_cursor (the cursor carries the window, so every page reads the same one; a cursor whose window starts more than 31 days ago is refused). Optionally of one severity or one kind (not both). One row per notable change: a repository force-pushed, renamed, gone, made private, archived or linked; a release published; a setup step of a commit the life runs turned dangerous; the website down, up or redirecting off-site; a TLS certificate or the domain expiring; the domain re-registered or its registrar changed; a link flagged or cleared. Each names its kind, severity, when it happened (occurred_at, with how that is known: time_basis), what changed (subject, plain text; link only when it may be clickable; withheld when assessed malicious) and fixed per-kind detail. Each row names its subnet slot and life (netuid, generation). Cached 5 minutes (slow class). Errors also: INVALID_DAYS, INVALID_SEVERITY, INVALID_KIND, INVALID_FILTER (both severity and kind). Errors are application/problem+json: INVALID_LIMIT, INVALID_CURSOR, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SERVICE_UNAVAILABLE (503), SOURCE_NOT_READY (503: change feeds are 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).

Query parameters

daysquery· integer · default 7 · 1 to 30

The window: changes that occurred in the last 1..30 days (default 7). Anything else is a 400 INVALID_DAYS.

severityquery· enum · one of info, notice, warning

Only changes of this severity: info, notice, warning. Not with kind (400 INVALID_FILTER); another value: 400 INVALID_SEVERITY.

kindquery· enum · one of repo_force_pushed, repo_renamed, repo_gone, repo_private, repo_returned, repo_archived, repo_unarchived, repo_taken_down, repo_owner_renamed, repo_owner_gone, repo_linked, repo_unlinked, head_restated, release_published, setup_risk_danger, site_down, site_up, site_redirect_offsite, website_added, website_removed, tls_expiring, domain_registered_after_life_start, domain_reregistered, domain_registrar_changed, domain_expiring, domain_unregistered, link_flagged, link_cleared

Only changes of this kind. Not with severity (400 INVALID_FILTER); another value: 400 INVALID_KIND. What changed (a closed list; a new kind is announced before it is served): repository repo_force_pushed, repo_renamed, repo_gone, repo_private, repo_returned, repo_archived, repo_unarchived, repo_taken_down, repo_owner_renamed, repo_owner_gone, repo_linked, repo_unlinked, head_restated, release_published, setup_risk_danger (a setup step of a commit the life runs turned dangerous); website site_down, site_up, site_redirect_offsite, website_added, website_removed, tls_expiring; domain domain_registered_after_life_start, domain_reregistered, domain_registrar_changed, domain_expiring, domain_unregistered; link link_flagged, link_cleared.

limitquery· integer · default 50 · 1 to 200

Changes per page, 1..200 (default 50). Anything else is a 400 INVALID_LIMIT.

cursorquery· string · up to 400 characters

meta.page.next_cursor of the previous page, sent back with the same other parameters (a cursor is bound to them; altered or foreign: 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 changes in the window, every life, newest first (occurred_at, then event_id, descending); each row names its subnet and life.

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_height for the first block. The subnet life the change belongs to.

life_start_heightinteger · unit block · can be null

The first block of the life generation names (GET /subnets/generations' start_height): use it, never generation, for heights, ages and dates. Null exactly when generation is null (root without a life, no subnet), or transiently when this API cannot read the lives. Root's generation 0 starts at 0.

is_current_lifeboolean · can be null

Whether generation is the slot's current life (true) or an ended one, re-registered since (false). Null exactly when generation is null, or transiently when this API cannot read the lives. Root's generation 0 is current.

event_idinteger · unit id

A stable id of the change (the tie-break of the order).

kindstring

What changed (a closed list; a new kind is announced before it is served): repository repo_force_pushed, repo_renamed, repo_gone, repo_private, repo_returned, repo_archived, repo_unarchived, repo_taken_down, repo_owner_renamed, repo_owner_gone, repo_linked, repo_unlinked, head_restated, release_published, setup_risk_danger (a setup step of a commit the life runs turned dangerous); website site_down, site_up, site_redirect_offsite, website_added, website_removed, tls_expiring; domain domain_registered_after_life_start, domain_reregistered, domain_registrar_changed, domain_expiring, domain_unregistered; link link_flagged, link_cleared. New values may be added; show an unknown value as is (or generically).

severitystring

info (worth knowing), notice (a change to check), warning (something may be wrong: code rewritten, the repository or site gone, the domain re-registered, a link flagged, a setup step dangerous). New values may be added; show an unknown value as is (or generically).

occurred_atstring (date-time)

When the change happened, best known (see time_basis), RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
time_basisstring

How occurred_at is known: source (a time the data states, e.g. a release's publish time, or one derived from it, e.g. 30 days before a domain expires), observed (when a check first saw the change: it happened at most one check interval before, hourly for repositories, daily for websites, domains and links). New values may be added; show an unknown value as is (or generically).

detected_atstring (date-time)

When the change was recorded, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
basisstring

live (recorded within 7 days of occurred_at), historical (derived later from stored history, e.g. when the life or the repository was first tracked). New values may be added; show an unknown value as is (or generically).

subject_kindstring

What subject names: repo, repo_owner, website, link, domain. New values may be added; show an unknown value as is (or generically).

subjectstring · can be null

What changed: the repository URL, the owner's login, the identity link (canonical form) or the domain. Plain text: it is a link only through link. Null with subject_reason.

subject_reasonstring · can be null

Why subject is null; null when it is served: withheld_unsafe (its link is assessed malicious now), unknown. New values may be added; treat unknown values as unavailable.

displaystring

How to render subject: link (a tracked repository, or a link assessed safe: link is set), text (a domain, a login, a link not assessed yet, or no subject), text_warning (assessed suspicious: text with a warning), hidden (assessed malicious: subject is null). Only link may be clickable. New values may be added; show an unknown value as is (or generically).

repo_idinteger · unit id · can be null

The tracked repository's id when subject_kind is repo (its images and advisories: GET /repos/{repo_id}/images, GET /repos/{repo_id}/advisories); null otherwise.

detailobject · can be null

Fixed keys per kind, e.g. repo_force_pushed {branch, default_branch, old_sha, new_sha, preserved}, site_* {from, to, http_status}, release_published {release_id, tag_name, prerelease}, link_flagged {verdict, previous_verdict, reason_categories}, tls_expiring {expires_at, days_left}; an unknown value is null. Times are RFC 3339 UTC, hashes lower-case hex; branch and tag_name are untrusted upstream text (render escaped).

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.