iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
GitHub’s new aggregate star-history endpoint replaces an inefficient and privacy-sensitive workaround: instead of downloading every person who currently stars a repository and rebuilding a timeline, a client can request daily counts across up to 30 calendar weeks at a time. For the roughly 251,000-star react/react example cited by GitHub on October 14, 2026, that changes full-history retrieval from about 2,511 requests to about 24.
Why the old star-history method stopped making sense
The stargazer endpoint answered a different question
The original GET /repos/{owner}/{repo}/stargazers endpoint was designed to answer “who starred this repository?” It returned a paginated list of people, with star timestamps available through a custom media type. Each page contained at most 100 stargazers.
Star-history tools reused that identity endpoint to answer “when did stars arrive?” A client had to fetch every page, discard the identities, and count timestamps by day. That was an expensive mismatch between an identity-list API and an aggregate time-series task.
There is also an important data-model limitation: the underlying star record represents people who still star the repository. When someone removes a star, that record disappears. The list therefore is not a permanent event log of every star and unstar action.
#1 Best Overall
Privacy and database pressure made the workaround costly
Public identity lists can be scraped to build targeting lists for spam and phishing. GitHub consequently restricted stargazer and watcher lists to repository administrators and collaborators. The restriction also addressed heavy traffic: in the week before access was limited, GitHub reported nearly 37,000 slow stargazer-count queries, averaging almost three seconds each, with more than 1,000 terminated by database safeguards.
After the restriction, GitHub reported about 60% fewer stargazer requests and about 80% less total time spent on count queries. The goal was not merely to block a use case; it was to provide a safer API that expresses the use case directly.
Old and new designs compared
| Area | Old stargazer-list workflow | Aggregate star-history endpoint |
|---|---|---|
| Primary answer | Which people currently star the repository? | How many current stars have creation dates on each day? |
| Privacy | Returns public identities, which can be collected for scraping. | Returns daily totals without attaching identities. |
| Request volume for about 251,000 stars | About 2,511 requests at 100 records per page. | About 24 requests when retrieving up to 30 calendar weeks per response. |
| Database work | Repeatedly paginates identity rows and reconstructs the chart client-side. | Filters an indexed created_at week range first, then groups matching rows by day. |
| Time navigation | Pages represent chunks of people, not reliable calendar periods. | Pages move backward through calendar-week ranges. |
| Historical meaning | Only stars still present are represented; removed stars leave no durable event. | Uses the same current-star semantics, expressed as aggregate counts. |
How the new endpoint reduces work
Filter by an indexed week range before grouping
The shipped design translates page and per_page into a calendar-week range on the indexed created_at column. It applies that range first and groups only matching records into daily counts. A response covers no more than 30 calendar weeks; increasing the page number moves farther back in the repository’s history.
For the react/react example, GitHub says this approach requires about 24 requests for the full period and examines roughly 251,000 rows across those ranges. That is substantially different from asking the database to aggregate the entire repository repeatedly for every page.
Why LIMIT and OFFSET alone would not solve it
A tempting implementation is to group all matching stars by day and then apply LIMIT and OFFSET to the grouped result. That can still force the database to scan, sort, and bucket the complete matching set before it can return a small page. GitHub estimates that, for the same example, 24 such requests could reprocess the full star set and examine roughly six million rows in total.
The meaningful optimization is therefore the time predicate before aggregation, not pagination by itself.
How to retrieve repository star history efficiently
- Choose the repository and date span. Decide whether you need the latest weeks, a fixed historical period, or the complete available history. The endpoint is organized around calendar weeks, so do not model its pages as rolling seven-day windows.
- Request a page of aggregate data. Use the endpoint’s
pageandper_pagecontrols. Set the page size to the largest value supported by the endpoint when you want fewer round trips; each response can cover up to 30 calendar weeks. - Store the daily rows as returned. Each result is already grouped by day. Keep the date and count together, and merge pages by date only if your application requests overlapping ranges or retries a response.
- Advance through older pages. Increment the page value to move backward through the repository’s calendar-week history. Stop when the response contains no older data or when you have reached the earliest date required by your chart.
- Cache completed ranges. Star-history charts are commonly refreshed more often than old weeks change. Cache historical pages and request only the newest range on subsequent updates. This reduces both API traffic and repeated database work.
- Design for rate limits and partial failure. Persist each successful page before requesting the next one. If a request fails, retry that page rather than restarting the entire history walk, and follow the rate-limit information returned by GitHub.
Semantics and limits you must account for
A calendar week is the unit of retrieval
The endpoint’s 30-week limit is a calendar-range limit, not a promise that every response contains the same number of rows. Month changes, year changes, and the repository’s first or last partial week can produce uneven boundaries. Keep the dates supplied by the API instead of reconstructing boundaries from request order.
Dense weeks can still be expensive
The endpoint limits the period examined per request but does not impose a fixed maximum number of stars inside that period. A repository with an unusually large launch, release, or news event can put a very dense week into one request. Time filtering reduces unnecessary scanning, but it cannot make a genuinely large matching range free.
Removed stars are not historical events
Because the star model stores the current set of people who still star a repository, removing a star removes its record. Daily totals therefore describe the creation dates of currently retained stars, not an immutable ledger of every star ever added. Applications should label charts accordingly rather than implying that they capture all past star actions.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Why this is a better API contract
The new design aligns the response with the reader’s actual need: aggregate counts without identity collection. It also makes the expensive part explicit. Clients request bounded calendar periods, while GitHub can use an index to narrow the rows before performing daily grouping. That improves privacy, reduces request volume, and avoids repeatedly rebuilding the same full-history aggregate.
“When the API change disrupted Star History, users rallied around the project. GitHub’s Community team listened and connected us with product engineering, who dug into our use case and worked alongside us to design a purpose-built endpoint. A difficult situation became a constructive collaboration between GitHub, Star History, and the broader community—ultimately leading to a better solution.”
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.— Tianzhou Chen, Star History maintainer and Bytebase co-founder
For developers maintaining a star-history chart, the practical rule is simple: use aggregate week-ranged requests, cache older pages, and treat the returned series as counts of stars that still exist. The result is a smaller, safer request pattern than scraping stargazer pages ever provided.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
