The network's timeline marks for charts, oldest first
https://api.bittensor.ai/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: 400INVALID_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 afterfrom_time: 400INVALID_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_cursorof the previous page, sent back with the same other parameters (a cursor is bound to them; altered or foreign: 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 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 SDKx.y.0),cli_release(a btclix.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_atis:exact(a time the source states),day(the date only:occurred_atis 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, alowone 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:publisherandannouncement_idname 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_kindisannouncement; 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) whensource_kindisannouncement; null otherwise.- linkstring · can be null
The release page, the announcement or the curated source, tracking parameters removed; null with
link_reason. Plain text unlesslink_displayislink: only then may it be rendered clickable.- link_reasonstring · can be null
Why
linkis null; null when it is set:no_link(none given),hidden_unsafe(assessed malicious: withheld). New values may be added; treat unknown values as unavailable.- link_verdictstring
The link's safety assessment:
safe,suspicious,malicious,unknown(not assessed yet, or no link). New values may be added; show an unknown value as is (or generically).- link_displaystring
How to render
link:link(assessed safe: the only value that may be clickable),text(not assessed yet, or no link: show as plain text),text_warning(assessed suspicious: text with a warning),hidden(assessed malicious:linkis null). New values may be added; show an unknown value as is (or generically).- 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), 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_RANGE
- INVALID_TIME
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RANGE_TOO_LARGE
- 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.