GitHub Star History API: What the Counts Actually Mean
GitHub’s new endpoint rebuilds your repository’s star chart without exposing who starred it. Does a spike on one day mean you gained that many stars that day?
- GitHub exposes repository star history as weekly totals with daily breakdowns, without returning user identities.
- A request covers up to 30 weeks; public resources allow unauthenticated access.
- The series describes stars that still exist, not a historical ledger of additions and removals.
You can recover the chart without recovering the user list
Tools that lost access to GitHub stargazer lists have a purpose-built alternative. The star-history endpoint announced on August 28 returns counts over time without individual identities. GitHub published a detailed account of its design on October 14.
The disruption followed restrictions on stargazer and watcher lists, which limited access to repository administrators and collaborators. Those lists had also supplied timestamps to charting tools. The new endpoint separates that analytics use case from access to individual user identities.
Pagination counts weeks, not stars
The REST API reference defines this request shape. Substitute the repository owner and name:
GET /repos/OWNER/REPO/stargazers/history?per_page=30&page=1| Field | Meaning |
|---|---|
per_page | Weeks per page; default and maximum: 30. |
page | Starts at 1, maximum 100; higher pages move backward. |
days | Daily counts, starting with Sunday. |
| Date boundaries | Not guaranteed to match UTC. |
Weeks arrive newest first, including zero-filled weeks with no stars. Public resources do not require authentication. For fine-grained tokens, the documented repository permission is Metadata: read.
Filter the input before aggregating it
In GitHub’s engineering example, reconstructing the history of react/react, with roughly 251,000 stars, fell from about 2,511 requests to 24.
The implementation narrows records to an indexed date range before counting them. Grouping every star and then applying pagination would still do the expensive work first. An exceptionally busy week can remain costly; fewer requests do not guarantee a proportional reduction in response time for every repository.
The series is not a net-growth ledger
In a September 11 reply on the official announcement, moraesc clarified that the endpoint counts creation dates only for stars still active today. It does not retain historical unstar events.
That distinction belongs in a dashboard’s labels. A date bucket cannot tell you when people later removed their stars, so it cannot reconstruct the repository’s net change on that date. Describe the series as the creation dates of surviving stars.
FAQ
Do I need collaborator access for a public repository?
No. The history endpoint permits unauthenticated requests for public resources; the identity-list restrictions are separate.
Does the curve measure product usage?
No. Repository stars are an interest signal. This response does not contain application usage or download counts.
Use the aggregate endpoint for a trend chart, then make the chart’s description match the data it actually returns.