To rebuild a GitHub repository’s star history without the stargazers list, you can use the GitHub Events API to fetch star events and reconstruct the timeline. This method works for any public repository, even if the stargazers list is disabled or the repo has been deleted, as long as the events are still available. Below is a detailed guide on how to do it, including the API calls, pagination handling, and common pitfalls.
Why You Might Need This
GitHub’s public API provides a /stargazers endpoint that lists users who starred a repository. However, this endpoint has limitations: it only shows the first 40,000 stargazers for unauthenticated requests, and it does not provide timestamps for when each star was added. If you need to see the growth trend over time, or if the repository has more than 40k stars, you must use the Events API instead. The Events API returns WatchEvent entries, each with a timestamp, which you can aggregate to build a star history. This is especially useful for analytics, visualizing growth, or comparing repos.
How the Events API Works
Every time a user stars a repository, GitHub records a WatchEvent in the repository’s event feed. You can access this feed via:
GET /repos/{owner}/{repo}/events?per_page=100
Each event object has a type field (e.g., WatchEvent) and a created_at timestamp. To get all star events, you need to paginate through the events, filtering only WatchEvent types. The API returns up to 100 events per page, and you can use the Link header to navigate to the next page. However, the Events API has a critical limitation: it only returns the last 300 events for a repository. This means if your repo has more than 300 stars, you will not get the full history from this endpoint alone. For older events, you must use the starred_at field from the stargazers endpoint (if available) or use the timeline endpoint for issues/PRs, but for stars specifically, the 300-event limit is a hard cap.
Step-by-Step Rebuilding Process
Here is a practical approach to rebuild the star history for a repository with 2500 stars over 24 days (as an example, but the method scales):
- Fetch all stargazers with timestamps – If the repo has fewer than 40k stars, use the stargazers endpoint with the
Accept: application/vnd.github.star+jsonheader to getstarred_attimestamps. Paginate through all pages (100 per page). - If stargazers endpoint is unavailable (e.g., repo deleted), fall back to the Events API, but be aware of the 300-event limit. You can only reconstruct the last 300 star events.
- Aggregate the timestamps – Once you have a list of
starred_atdates, sort them and count cumulative stars per day (or per hour) to build a timeline. - Handle pagination correctly – Always check the
Linkheader forrel="next"and continue until no next page exists. Respect rate limits (60 requests/hour unauthenticated, 5000/hour with a token). - Store the data – Save the timestamps in a CSV or database for further analysis.
For the example of 2500 stars over 24 days, you would typically have about 104 stars per day. But the actual distribution may vary.
Common Pitfalls and Limitations
- 300-event limit – The Events API only provides the most recent 300 events. For repos with more than 300 stars, you cannot get the complete history from events alone. You must use the stargazers endpoint with the custom media type.
- Rate limiting – Unauthenticated requests are limited to 60 per hour. Fetching 2500 stars requires 25 requests (100 per page), which is fine, but if you hit the limit, you need to wait or use a token.
- Deleted repositories – If a repo is deleted, its events are also removed, so you cannot rebuild history from the API. You would need a third-party archive like GH Archive or a local backup.
- Time zone – Timestamps are in UTC. If you want local dates, convert accordingly.
- Star events vs. unstar events – The Events API does not include unstar events, so your history will only show cumulative stars, not net growth (stars minus unstars). The stargazers list only shows current stargazers, so it also misses users who unstarred.
Alternative: Using GH Archive
If you need a complete history beyond the API limits, the GH Archive (gharchive.org) provides a public dataset of all GitHub events since 2011. You can query it for WatchEvent for a specific repo and build a full timeline. This is the most reliable method for large repos or historical data. For example, you can use Google BigQuery to run a SQL query like:
SELECT DATE(created_at) as day, COUNT(*) as stars
FROM `githubarchive.day.20240101`
WHERE type = 'WatchEvent' AND repo.name = 'owner/repo'
GROUP BY day ORDER BY day;
This gives you exact daily star counts. The GH Archive is free and updated hourly, making it ideal for analysis.
How to Choose the Right Method
Your choice depends on the repository size and data availability:
- Repo has fewer than 300 stars and you need timestamps – Use the Events API (simple, no auth needed).
- Repo has 300-40k stars and you need timestamps – Use the stargazers endpoint with the star+json media type.
- Repo has more than 40k stars or is deleted – Use GH Archive (requires external querying).
- You only need the current star count and not history – Use the repository’s
stargazers_countfield.
For the specific scenario of 2500 requests over 24 days, the stargazers endpoint is the best choice because it provides timestamps and stays within rate limits.
Costs and Rate Limits
GitHub API is free, but rate limits apply: 60 requests per hour for unauthenticated, 5000 per hour with a personal access token. Fetching 2500 stargazers requires 25 requests, which is well within the limit. If you need to fetch many repos, you may need to optimize or use conditional requests (If-Modified-Since) to reduce load. No monetary cost is involved, but you must respect the API terms of service.
Safety and Accuracy Considerations
When rebuilding history, be aware that the data may not be perfectly accurate due to unstar events. The stargazers list only includes current stars, so if users unstarred, your history will overcount early periods. The Events API, on the other hand, only includes star events, not unstar events, so it also overcounts. For precise net growth, you would need to track unstar events, which are not publicly available. For most analytical purposes, the cumulative star count is sufficient, but you should note the limitation.
Frequently Asked Questions
Can I get star history for a private repository?
No, the API only exposes events and stargazers for public repositories. For private repos, you would need to be an owner or have admin access, and even then, the events API may not include star events for private repos.
What if the repository has been renamed?
If the repo is renamed, the API still works with the new name. However, historical events are tied to the repo ID, not the name. If you use the API with the new name, you will get events for that repo, including those from before the rename. For GH Archive, you need to filter by repo ID, not name, to avoid missing events.
How do I handle pagination with the stargazers endpoint?
Use the Link header in the response to find the next page URL. Continue fetching until the header no longer contains a rel="next". Alternatively, you can use a library like Octokit that handles pagination automatically.
Why does my star history show fewer stars than the repo’s count?
This can happen if you are using the Events API and the repo has more than 300 stars, or if you are not fetching all pages of the stargazers list. Also, if users have unstarred, the current count will be lower than the cumulative total. Ensure you fetch all pages and consider using the GH Archive for complete data.
Can I export the star history to a CSV?
Yes, after fetching the timestamps, you can write them to a CSV file using any programming language. The process is straightforward: parse the JSON, extract starred_at and login, and write to a file.
Is there a way to see star history on the GitHub website?
GitHub does not provide a built-in star history chart. You can use third-party tools like Star History (star-history.com) that rely on the same API methods described here. These tools are free and provide interactive charts.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Car Trends Making Cars Worse: 7 Downsides
- Nostalgic Classic Games Revamped on G2A?
- Nvidia RTX 4000 Super GPUs: Full Specs & Buying Guide
- Photoshop vs Lightroom AI Features Compared
- DNF vs DNF5: Which Package Manager?
- Korean SUV Making BMW and Audi Owners Question Their Choices?