Skip to content
TAO$188.12
BTC0.002928
MCap$2.21B
Vol$86.07M

API reference / Subnets

A tracked repository's star and fork history, by UTC day

GET/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_id of a subnet's repo).

Query parameters

from_dayquery· string (date)

The first UTC day, inclusive, YYYY-MM-DD (default: 3660 days before to_day). Not a day: 400 INVALID_DAY.

Format: date, YYYY-MM-DD
to_dayquery· string (date)

The last UTC day, inclusive, YYYY-MM-DD (default: today). Not a day: 400 INVALID_DAY; before from_day: 400 INVALID_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_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.

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 with stars_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 past stars_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 with forks_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 past forks_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_from to stars_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 beside stars_total, never reconciled with it. Null with current_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, private or taken_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), 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.