A tracked repository's star and fork history, by UTC day
https://api.bittensor.ai/api/v2/repos/{repo_id}/star-history- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
One row per UTC day on which at least one star or fork was added, oldest first (day), in the inclusive window [from_day, to_day] (meta.window; default the 3660 days up to today, the whole history today; at most 3660 days), keyset-paged through meta.page.next_cursor (the cursor carries the window). Days without a row: inside the list's coverage (stars_covered_from to stars_complete_through) a day without a row added nothing: carry the previous row's stars_total / forks_total forward. Outside it a figure is null with its *_reason (not_read_yet, beyond_list_cap, not_checked_yet), never 0. The totals count additions only (removals are invisible), so they can exceed the host's current counts (current_stars, current_forks), which are served beside them, never reconciled. Cached 5 minutes (slow class). Errors are application/problem+json: INVALID_ID (400: repo_id), REPO_NOT_FOUND (404: no tracked repository has this id), INVALID_LIMIT, INVALID_CURSOR, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SERVICE_UNAVAILABLE (503), INVALID_DAY, INVALID_RANGE (from_day after to_day), RANGE_TOO_LARGE, SOURCE_NOT_READY (503: star histories 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).
Path parameters
- repo_idpath, required· integer · 1 to 9223372036854776000
The tracked repository's id (
repo_idof a subnet's repo).
Query parameters
- from_dayquery· string (date)
The first UTC day, inclusive,
YYYY-MM-DD(default: 3660 days beforeto_day). Not a day: 400INVALID_DAY.- Format: date, YYYY-MM-DD
- to_dayquery· string (date)
The last UTC day, inclusive,
YYYY-MM-DD(default: today). Not a day: 400INVALID_DAY; beforefrom_day: 400INVALID_RANGE.- Format: date, YYYY-MM-DD
- limitquery· integer · default 1000 · 1 to 2000
Days per page, 1..2000 (default 1000). 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.
One row per UTC day on which at least one star or fork was added, oldest first. A day without a row added nothing: carry the previous row's stars_total / forks_total forward.
- daystring (date)
The UTC day (the order key).
- Format: date, YYYY-MM-DD
- stars_addedinteger · unit count · can be null
Stars first listed on this day. Null with
stars_reason.- stars_totalinteger · unit count · can be null
Stars counted up to and including this day. It never decreases (removals are invisible to the list), so it can exceed
current_stars. Null withstars_reason.- stars_reasonstring · can be null
Why the star figures are null; null when they are set:
not_read_yet(the history read has not reached this day),beyond_list_cap(the list is longer than the host lists, 40,000: not countable paststars_complete_through),not_checked_yet(after the last read). New values may be added; treat unknown values as unavailable.- forks_addedinteger · unit count · can be null
Forks first listed on this day. Null with
forks_reason.- forks_totalinteger · unit count · can be null
Forks counted up to and including this day (never decreases; can exceed
current_forks). Null withforks_reason.- forks_reasonstring · can be null
Why the fork figures are null; null when they are set:
not_read_yet(the history read has not reached this day),beyond_list_cap(the list is longer than the host lists, 40,000: not countable pastforks_complete_through),not_checked_yet(after the last read). New values may be added; treat unknown values as unavailable.- stars_truncatedboolean
The star list is longer than the host lists (40,000): counted only from
stars_covered_fromtostars_complete_through.- forks_truncatedboolean
As
stars_truncated, for forks.- stars_covered_fromstring (date-time) · can be null
The oldest star counted (the series starts here), RFC 3339 UTC; null: none counted yet.
- Format: date and time, ISO 8601 in UTC
- stars_complete_throughstring (date-time) · can be null
Every star listed up to this time is counted, RFC 3339 UTC: a day is final once it ends before it. Null: not read yet.
- Format: date and time, ISO 8601 in UTC
- forks_covered_fromstring (date-time) · can be null
As
stars_covered_from, for forks.- Format: date and time, ISO 8601 in UTC
- forks_complete_throughstring (date-time) · can be null
As
stars_complete_through, for forks.- Format: date and time, ISO 8601 in UTC
- current_starsinteger · unit count · can be null
The repository's star count as the host reports it now (net of removals), as of
current_counts_at; served besidestars_total, never reconciled with it. Null withcurrent_reason.- current_forksinteger · unit count · can be null
The fork count as the host reports it now. Null with
current_reason.- current_reasonstring · can be null
Why the current counts are null; null when they are set:
not_checked_yet. New values may be added; treat unknown values as unavailable.- current_counts_atstring (date-time) · can be null
When the current counts were read, RFC 3339 UTC; null when not read yet.
- Format: date and time, ISO 8601 in UTC
- upstream_statusstring
ok,not_found,privateortaken_down: a repository gone from the host keeps its history (it is no longer read). New values may be added; show an unknown value as is (or generically).- as_ofstring (date-time)
The older of the star and fork lists' last reads, 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_DAY
- INVALID_ID
- INVALID_LIMIT
- INVALID_RANGE
- PAYMENT_REQUIRED
- RANGE_TOO_LARGE
- RATE_LIMITED
- REPEATED_PARAMETER
- REPO_NOT_FOUND
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.