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

API reference / Network

The network's timeline marks for charts, oldest first

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

Marks for charts of network-wide figures.

Full description

Marks for charts of network-wide figures (emission, stake, price): runtime, SDK and CLI releases, network upgrades, emission halvings, governance changes and incidents, in the half-open window [from_time, to_time) (meta.window; default the 3660 days up to now snapped up to the hour, the whole history today; at most 3660 days), oldest first (occurred_at, then event_id), keyset-paged through meta.page.next_cursor (the cursor carries the window). Each mark says how precise its time is (time_precision), how it was made (basis: derived by fixed rules, or curated), how sure it is (confidence) and where it comes from (source_kind), exactly as recorded. Every mark is served, a low-confidence one (an announcement's title matched a rule: a candidate, not a fact) included: the client decides how to show it. A runtime_release is when the release was published, not when the chain enacted it. A link is served with its safety assessment (link_verdict) and how to render it (link_display): only link_display link may be clickable; a link assessed malicious is withheld (link null, link_reason hidden_unsafe). Titles and excerpts are publisher text: render them as plain text. A retracted mark (its source deleted or withdrawn) is not served. Cached 5 minutes (slow class). Errors also: INVALID_TIME, INVALID_RANGE (from_time not before to_time), RANGE_TOO_LARGE. Errors are application/problem+json: INVALID_LIMIT, INVALID_CURSOR, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SERVICE_UNAVAILABLE (503), SOURCE_NOT_READY (503: network announcements and events 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

from_timequery· string (date-time)

The window's start, inclusive: RFC 3339 with an offset (default: 3660 days before to_time). Not a time: 400 INVALID_TIME.

Format: date and time, ISO 8601 in UTC
to_timequery· string (date-time)

The window's end, exclusive: RFC 3339 with an offset (default: now snapped up to the hour). Not a time: 400 INVALID_TIME; not after from_time: 400 INVALID_RANGE.

Format: date and time, ISO 8601 in UTC
limitquery· integer · default 500 · 1 to 1000

Marks per page, 1..1000 (default 500). 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 marks in the window, oldest first (occurred_at, then event_id).

event_idinteger · unit id

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

kindstring

What happened: runtime_release (a subtensor runtime release was published: when it was released, not when the chain enacted it; releases are sometimes published out of order), sdk_release (a bittensor SDK x.y.0), cli_release (a btcli x.y.0), network_upgrade, emission_halving, governance_change, incident (a halt, pause, exploit, security or scam alert). A closed list; a new kind is announced before it is served. New values may be added; show an unknown value as is (or generically).

occurred_atstring (date-time)

When it happened, to time_precision, RFC 3339 UTC (the order's first key).

Format: date and time, ISO 8601 in UTC
time_precisionstring

How precise occurred_at is: exact (a time the source states), day (the date only: occurred_at is midnight UTC), month (the month only). New values may be added; show an unknown value as is (or generically).

titlestring

A short label, plain text (render escaped), at most 200 characters.

basisstring

derived (by fixed rules, from releases or an announcement's title), curated (entered by hand from a named source). New values may be added; show an unknown value as is (or generically).

confidencestring

How sure the mark is: high (a release, or curated with a primary source), medium (curated from reports), low (an announcement's title matched a rule: a candidate, not a fact). Every mark is served, a low one included: decide how to show it (e.g. a hollow marker). New values may be added; show an unknown value as is (or generically).

source_kindstring

Where the mark comes from: release (a published release), announcement (an announcement: publisher and announcement_id name it), curated. New values may be added; show an unknown value as is (or generically).

publisherstring · can be null

The announcement's publisher when source_kind is announcement; null otherwise. Known values: otf, latent, rao, docs. New values may be added; show an unknown value as is (or generically).

announcement_idinteger · unit id · can be null

The announcement's announcement_id (GET /network/announcements) when source_kind is announcement; null otherwise.

detailobject

Fixed keys per kind: runtime_release {project, tag, spec_version (null for tags that name none)}, sdk_release / cli_release {project, version}, the others {rule} (derived from an announcement's title) or {curated_id, note} (curated). Text in it is plain text (render escaped).

first_seen_atstring (date-time)

When the mark was first recorded, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
as_ofstring (date-time)

The mark's last change (its derivation or curation), RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC

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.