• Since July 2026, GET /repos/{owner}/{repo}/stargazers only works for repo admins and collaborators. A token doesn't help if you're neither.
• If you only need the growth curve, GitHub shipped GET /repos/{owner}/{repo}/stargazers/history on 2026-09-04. It returns star counts per week and per day, with no user identities.
• For public repos it returned 200 without a token when I tested it (unauthenticated limit: 60 requests/hour).
• Last checked: 2026-10-19.

Your README's star history chart went blank one day, and curl gives you a 401. I build a tool that draws GitHub star charts, so I ran straight into this change. These are my notes.

Symptoms and what they mean

Logging in doesn't fix it. The rule is "admins and collaborators only", not "authentication required", so a token still won't list stargazers for someone else's repo.

What changed

The affected endpoints are /repos/{owner}/{repo}/stargazers (who starred) and /repos/{owner}/{repo}/subscribers (watchers). /users/{username}/subscriptions was deprecated.

The reason is spam. Public stargazer lists were being scraped in bulk and used as target lists for spam and phishing.

But tools like star-history.com built their charts by stacking up the timestamps in that list, so they broke too.

/stargazers/history: weekly star counts, no identities

GET /repos/{owner}/{repo}/stargazers/history returns star counts grouped by calendar week, without saying who starred. Each week includes 7 daily counts, and one request returns up to 30 weeks.

Here's an unauthenticated call against octocat/Hello-World on 2026-10-19:

$ curl -i -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2026-03-10" \
    "https://api.github.com/repos/octocat/Hello-World/stargazers/history?per_page=2"
HTTP/2 200
link: <…/stargazers/history?per_page=2&page=2>; rel="next", <…/stargazers/history?per_page=2&page=100>; rel="last"
x-github-api-version-selected: 2026-03-10

[{"week":1792281600,"total":7,"days":[7,0,0,0,0,0,0]},
 {"week":1791676800,"total":52,"days":[32,3,4,5,5,1,2]}]

• week: start of the week (Unix seconds)
• days: daily counts for that week, 7 values starting on Sunday
• total: the week's sum

So you get daily resolution, not just weekly. The shape matches /stats/commit_activity.

It also worked without X-GitHub-Api-Version (GitHub then picks 2022-11-28), but I'd send the header anyway.

Auth and rate limits: 60/hour without a token

For public repos I got 200 without a token. The headers said x-ratelimit-limit: 60 and x-ratelimit-resource: core, the same 60 requests/hour as the rest of the unauthenticated REST API. The docs don't explicitly say "no auth required", so treat this as what I saw, not a promise.

The endpoint page doesn't list the authenticated limit or which fine-grained token permission it needs, and I haven't tested those yet, so I won't guess.

Re-requesting with the ETag gives a 304. But GitHub's best-practices page says a 304 only skips the rate limit when the request has an Authorization header. Without a token, assume it still counts.

Getting the full history: paginate until you get []

Start at page=1 and keep going until the response is []. For octocat/Hello-World (created in 2011), data ran through page 28. Page 29 returned [] and page 101 returned 422.

$ curl -s "https://api.github.com/repos/octocat/Hello-World/stargazers/history?page=29"
[]
$ curl -s "https://api.github.com/repos/octocat/Hello-World/stargazers/history?page=101"
{"message":"Pagination is limited to 100 pages.", … "status":"422"}

The number of requests is roughly "weeks the repo has existed ÷ 30". It doesn't depend on how many stars the repo has.

Watch out: with per_page below 30, the rel="last" link in the Link header points at page=100. That's the page cap, not the real last page. With per_page=30 it pointed at the real last page (28 for Hello-World).

A cumulative star CSV in plain Python

Standard library only. It fetches every page, flips them to oldest first, and keeps a running total.

# star_history.py: build a cumulative star CSV from GitHub's /stargazers/history
import json, sys, urllib.request
from datetime import datetime, timezone

repo = sys.argv[1]  # e.g. octocat/Hello-World
weeks, page, calls = [], 1, 0
while page <= 100:  # page is capped at 100
    url = f"https://api.github.com/repos/{repo}/stargazers/history?per_page=30&page={page}"
    req = urllib.request.Request(url, headers={
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2026-03-10",
    })
    with urllib.request.urlopen(req) as res:
        batch = json.load(res)
    calls += 1
    if not batch:  # pages older than the creation week return []
        break
    weeks.extend(batch)
    page += 1

weeks.reverse()  # newest-first -> oldest-first
total = 0
print("week_start,new_stars,cumulative")
for w in weeks:
    total += w["total"]
    day = datetime.fromtimestamp(w["week"], tz=timezone.utc).date()
    print(f"{day},{w['total']},{total}")
print(f"# {repo}: {len(weeks)} weeks, {calls} requests, total {total}", file=sys.stderr)

$ python3 star_history.py octocat/Hello-World > hello.csv
# octocat/Hello-World: 822 weeks, 29 requests, total 3857
$ head -3 hello.csv
week_start,new_stars,cumulative
2011-01-23,62,62
2011-01-30,1,63

On 2026-10-19 that pulled 822 weeks in 29 requests. The last request is just the [] check.

One thing I can't explain yet: at 2026-10-18 17:29 UTC, GET /repos/octocat/Hello-World/stargazers/count returned {"count": 3858} and stargazers_count on the repo said 3858 too. The history added up to 3857, and rerunning the script right after still gave 3857. So it's off by one, and I don't know why.

Feed the CSV to any chart library and you have a cumulative chart. If you only care about recent growth, per_page=1 is a single request that returns this week's daily counts:

$ curl -s "https://api.github.com/repos/octocat/Hello-World/stargazers/history?per_page=1"
[{"week":1792281600,"total":7,"days":[7,0,0,0,0,0,0]}]

Caveats

1. Unstars disappear. When someone removes a star, the record is gone. The cumulative chart shows when current stargazers starred, so it can come out lower than numbers you saw in the past, and it can't show a drop.
2. Week and day boundaries may not be UTC. The docs say "Week and day boundaries are not guaranteed to align with UTC." My script prints UTC dates, so a date can look one day off.
3. No date range filter. You walk back from the newest page.
4. No identities. You can't build "a famous dev starred your repo" features on this.
5. A 422 can also mean "endpoint has been spammed". The threshold isn't public.
6. Weeks with a huge spike of stars can be slow. GitHub calls this a remaining scaling issue.

Why 2,511 requests became 24

GitHub's engineering post uses react/react (about 251k stars) as the example: about 2,511 requests for full history on the old API, about 24 on the new one.

Their first attempt aggregated everything up front and paginated with OFFSET/LIMIT. That got requests down to 24, but the database still scanned about 6 million rows. Small responses don't make a query cheap.

The version that shipped turns page numbers into indexed date ranges, so it filters by period first and aggregates second. That scans about 251k rows, roughly one read per star.

Putting a star chart in your README

A few options:

• Generate an SVG with GitHub Actions. Run the script above on a schedule and commit the SVG. No third-party dependency, so it's the most stable, but you maintain the workflow.
• star-history.com, a popular site for star charts. GitHub's engineering post quotes its maintainer, Tianzhou Chen. I haven't confirmed whether it uses the new endpoint.
• GitHubCard, the profile and repo card tool I'm building. I switched it to this endpoint, so you can now add a star history chart for any public repo, including ones you don't own, without signing in (saving and publishing still need a login). How it works is on our product blog.

If you just want one chart, star-history.com is probably enough. If you'd rather not depend on an outside service, use Actions.

Wrap-up

GitHub stopped publishing who starred a repo. When and how many is still available through the new endpoint. For a growth curve, paginating /stargazers/history is enough. Just keep in mind that unstars aren't counted and that week and day boundaries aren't guaranteed to be UTC.

I'll update this post once I've tested the authenticated behavior.

References

1. New API endpoint provides privacy-safe star history data (GitHub Changelog, 2026-09-04)
2. From 2,500 requests to 24: Rebuilding star history without the stargazers (GitHub Blog, 2026-10-14)
3. REST API endpoints for starring: Get repository star history (GitHub Docs)
4. Upcoming access restrictions to public API endpoints and UI views (GitHub Changelog, 2026-06-30)
5. Best practices for using the REST API (GitHub Docs)

Almost always, the problem is the public service that draws the card, not your Markdown. Below is how I narrow it down, and three fixes that actually last.

Last verified: Oct 14, 2026.

TL;DR

Step 1: Is it you or the service?

Copy the image URL out of your README and open it straight in your browser. Or check the headers:

curl -I "https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME"
curl -I "https://streak-stats.demolab.com/?user=YOUR_USERNAME"

• 200 with image/svg+xml and a normal card: the service is fine. The problem is in your README (see Step 6) or a stale cached copy on GitHub.
• 200 but the SVG says "Something went wrong": the service is up but couldn't fetch your data. This is usually a rate limit.
• 503: the instance itself is down or paused.
• 403: the endpoint is refusing the request.

When I checked on Oct 14, both public endpoints returned 200. They work most days, but they go down every so often, so "it works right now" doesn't mean it'll still work tomorrow.

Step 2: Know why the public instances break

503 DEPLOYMENT_PAUSED. In #3851 ("Public deployment paused"), the maintainers explain that Vercel's sponsorship ended. They point people to GitHub Actions or self-hosting instead. #4737 and #4798 ("not working again ?") are both still open. The repo README now also says the project is no longer maintained and recommends its successor, GitHub Stats Extended.

Rate limits. The README says the public instance is "best-effort and can be unreliable due to rate limits and traffic spikes." Thousands of profiles share one pool of GitHub API requests. When that pool runs out, you get the error card.

403 on Streak Stats. In streak #872, users reported every public streak endpoint returning 403. That issue is closed now, but it can happen again.

Broken image, no error. GitHub doesn't load README images straight from the source. It serves them through its own image proxy (camo). If the card service is slow, the image may just not appear. Users have reported this in streak #754 and #792.

Step 3 (recommended): Generate the SVGs with GitHub Actions

This is the fix that holds up best. A workflow builds the cards on a schedule and commits them to your profile repo. Your README then points at a file in your own repo, with no outside service in the way.

Stats and top languages card. Save this as .github/workflows/grs.yml in your USERNAME/USERNAME repo. It's adapted from the action's README:

name: Update README cards
on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v6
      - uses: stats-organization/github-readme-stats-action@v2
        with:
          card: stats
          options: username=${{ github.repository_owner }}&show_icons=true
          path: profile/stats.svg
          token: ${{ secrets.GITHUB_TOKEN }}
      - uses: stats-organization/github-readme-stats-action@v2
        with:
          card: top-langs
          options: username=${{ github.repository_owner }}&layout=compact
          path: profile/top-langs.svg
          token: ${{ secrets.GITHUB_TOKEN }}
      - uses: stats-organization/github-readme-stats-action@v2
        with:
          card: stats
          options: username=${{ github.repository_owner }}&show_icons=true&theme=dark
          path: profile/stats-dark.svg
          token: ${{ secrets.GITHUB_TOKEN }}
      - name: Commit cards
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add profile/*.svg
          git commit -m "Update README cards" || exit 0
          git push

Then in your README:

![Stats](./profile/stats.svg)
![Top Languages](./profile/top-langs.svg)

To include private repo stats, create a PAT with the repo and read:user scopes. Store it as a repository secret and use it in place of GITHUB_TOKEN. Never paste the token into the YAML.

Streak card. Add .github/workflows/streak-stats.yml, following the Streak Stats README:

      - name: Generate streak stats
        uses: DenverCoder1/github-readme-streak-stats@v1
        with:
          options: user=${{ github.repository_owner }}&theme=default&disable_animations=true
          path: profile/streak.svg
          token: ${{ secrets.STREAK_STATS_TOKEN }}

(Use the same checkout and commit steps as above.) The token line is only needed for private contributions. The README says to use a PAT with the repo scope, stored as a secret.

The catch: the cards only update when the workflow runs, once a day here. For a profile README, that's usually fine.

Step 4: Self-host on Vercel

If you want cards that update live, deploy your own instance:

1. Fork the repo. The original README still has a Vercel guide, and GitHub Stats Extended has its own deploy docs.
2. Import the fork into Vercel.
3. Create a GitHub PAT and add it as an environment variable named PAT_1.
4. Deploy, then swap the domain in your README:

![Stats](https://YOUR-APP.vercel.app/api?username=YOUR_USERNAME&cache_seconds=21600)

That last step trips people up. #4747 covers cases where a self-hosted fork still looked broken because the README still pointed at the public URL. Check the URL.

On caching: cache_seconds takes values from 21600 to 86400, and the default is 21600. On your own instance, you can set the CACHE_SECONDS environment variable instead. On Vercel's free plan, keep in mind that your own usage counts against your own limits.

Step 5: Top languages card looks wrong

Two things come up a lot. The card only looks at your first 100 repos, and by default it ranks languages by byte count. One big Jupyter notebook can push everything else off the card.

![Top Langs](https://YOUR-APP.vercel.app/api/top-langs/?username=YOUR_USERNAME&hide=jupyter%20notebook&exclude_repo=old-fork&size_weight=0.5&count_weight=0.5)

size_weight=0.5&count_weight=0.5 is the combination the README recommends. It weighs bytes and repo count together. To stop GitHub from counting notebooks at all, add a .gitattributes file to that repo:

*.ipynb linguist-vendored

Step 6: The boring causes

Before you change anything else, check these:

• A typo in the username, or a stray \& copied from a doc.
• user= vs username=. Streak Stats uses user, github-readme-stats uses username.
• A renamed account.
• A cached old version. Wait for the cache to expire before you assume it's broken.

For dark/light mode, use the light and dark SVGs the workflow writes above:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./profile/stats-dark.svg" />
  <img src="./profile/stats.svg" alt="GitHub stats" />
</picture>

Alternatives

If you'd rather not maintain a workflow at all, there are a few options. GitHub Stats Extended is the maintained successor and has its own public instance. The two GitHub Actions above are the most robust free option. Community-run public instances exist too, but they're third-party and nobody promises they'll stay up.

Full disclosure: I work on GitHubCard. GitHubCard is a hosted card editor: you design stats, top languages, streak and other widgets as one card, then embed it with a single line:

![GitHub profile card](https://githubcard.com/YOUR_USERNAME.svg)

It's a hosted service too, so the same logic applies: if the card has to be up 100% of the time, a static SVG committed by an Action is still the safest choice.

Sources (accessed Oct 14, 2026)

• github-readme-stats README and issues #3851, #4737, #4747, #4798
• stats-organization/github-readme-stats-action
• DenverCoder1/github-readme-streak-stats, issues #754, #792, #872

Last verified: Oct 14, 2026.

I've rewritten mine a few times. Below are five templates I'd actually use, depending on what kind of developer you are, plus a few rules that keep them from rotting.

First: the 30-second setup

If you haven't made one yet:

1. Create a new public repository with exactly the same name as your GitHub username (e.g. octocat/octocat).
2. Add a README.md to it.
3. Whatever is in that file shows up at the top of your profile.

That's it. Everything below is just Markdown (plus a bit of HTML that GitHub allows).

Template 1: The minimal one

Good if you don't want to maintain anything. Three lines of who you are, three links, done.

# Hi, I'm Sam

Backend developer. I mostly work on Go services and Postgres.
Currently: building internal tooling at a logistics startup.

- Blog: https://example.dev
- X: https://x.com/yourhandle
- Email: you@example.dev

Honestly, this beats most "fancy" profiles. A recruiter or another dev can read it in five seconds.

Template 2: The open source maintainer

If people land on your profile because of a project, send them back to it. Pin the repos too, but a short list with one-line descriptions does more than pins alone.

# Sam Doe

I maintain a few small libraries for working with CSV and time series data.

## Projects

| Project | What it does |
|---|---|
| [fastcsv](https://github.com/you/fastcsv) | Streaming CSV parser, zero deps |
| [tsbucket](https://github.com/you/tsbucket) | Downsample time series in the browser |

## Contributing

Issues and PRs welcome. Start with anything labelled `good first issue`.

Tables render fine on GitHub and stay readable on mobile as long as you keep them to two or three columns.

Template 3: The job seeker

Here the goal is to answer "what can this person do, and can I see proof?" quickly.

# Sam Doe — Full-stack developer

React, TypeScript, Node.js, PostgreSQL. 4 years shipping SaaS products.

**Open to:** remote full-stack roles

## Things I've built
- **Invoicer** — multi-tenant billing app (Next.js, Stripe). [Live](https://example.dev) · [Code](https://github.com/you/invoicer)
- **Queue-lite** — Postgres-backed job queue. [Code](https://github.com/you/queue-lite)

## Contact
you@example.dev · [LinkedIn](https://linkedin.com/in/you)

Put "open to" near the top. People skim.

Template 4: The writer

If you blog, your profile can act as an index. You can update the list by hand, or automate it with a GitHub Action that pulls your RSS feed (there are several on the Marketplace; search "blog post workflow").

# Sam Doe

Fullstack developer. Writing about system design.

## Recent posts
<!-- BLOG-POST-LIST:START -->
- [Designing idempotent webhooks](https://example.dev/idempotent-webhooks)
- [Why I stopped using ORMs for reporting queries](https://example.dev/orm-reporting)
<!-- BLOG-POST-LIST:END -->

The HTML comments are markers that RSS actions typically use to know where to write. They're invisible on the rendered page.

Template 5: The stats-and-visuals one

This is the template most people actually want: a short intro plus some visual summary of your GitHub activity: stats, top languages, streak, contribution graph.

The usual way to do this is to stack several embeds from different services:

![Stats](https://github-readme-stats.vercel.app/api?username=you&show_icons=true)
![Top langs](https://github-readme-stats.vercel.app/api/top-langs/?username=you&layout=compact)
![Streak](https://streak-stats.demolab.com?user=you)
![Activity](https://github-readme-activity-graph.vercel.app/graph?username=you)

It works, but each one has its own theme parameters, and they never quite line up visually. When one of the services is down or rate limited, you get a broken image in the middle of your profile.

The alternative I've been using is to put all of that into one image. Full disclosure: I work on GitHubCard, which does exactly this. You drag widgets (profile stats, streak, contribution heatmap, top languages, top repos, star history, and so on) onto a canvas, theme them once, and embed a single SVG:

# Hi, I'm Sam 👋

Full-stack developer building useful products.

![GitHubCard](https://githubcard.com/you.svg)

## Featured projects
- ...

Replace you with your username. With no custom design it renders a default card; if you design and save one in the editor (that part needs a GitHub sign-in), you copy the link it gives you instead. Data refreshes from GitHub but is cached, so changes can take up to an hour to show. For a repo, the same idea works with githubcard.com/owner/repo.

Whatever tool you use, the point is the same: one visual, not six.

Rules I use to keep a profile README useful

1. Keep the top 10 lines for the important stuff. On a laptop screen, that's roughly what people see before scrolling. Name, what you do, what you're working on, how to reach you.

2. Don't list every technology you've touched. A row of 30 logo badges says "I've opened a lot of tutorials". Five you'd be comfortable being interviewed on is more convincing.

3. Avoid anything that goes stale. "Currently learning Rust" from 2022 is worse than nothing. If you include a "currently" line, either update it or automate it.

4. Check it on mobile. Open your profile on your phone. Wide tables, side-by-side images with align="left", and huge GIFs often fall apart there.

5. Watch the number of external images. Every embed is another request to another service. Fewer embeds means a faster profile and fewer broken-image icons.

6. Use alt text. ![GitHub stats for Sam](...) instead of ![](...). It helps screen readers, and it's what shows when an image fails to load.

A combined starter you can copy

If you just want something to paste and edit:

# Hi, I'm <Name> 👋

<One line: what you do.> <One line: what you're working on now.>

![GitHub profile card for <username>](https://githubcard.com/<username>.svg)

## Featured projects
- **[project-one](https://github.com/<username>/project-one)** — what it does, in one line
- **[project-two](https://github.com/<username>/project-two)** — what it does, in one line

## Writing
- [Your best post](https://example.dev/post)

## Contact
<email> · [X](https://x.com/<handle>)

Swap the image line for whatever stats setup you prefer, or delete it. The rest is the part that actually tells people who you are.

If you have a profile README you're proud of, drop the link in the comments. I'm always looking for layouts to steal.

Step 1: Set up your profile README

If you don't have one yet:

1. Create a public repository with the exact same name as your username (e.g. alex/alex).
2. Add a README.md.

GitHub renders that file at the top of your profile.

Step 2: Add a card with streak stats

The usual approach is a dedicated streak service with its own URL and theme parameters. If you already use separate cards for stats and languages, that's another host and another set of colors to match.

An alternative is to put the streak on the same card as everything else. With GitHubCard, a default card is a single URL, no sign-in needed:

[![GitHub card](https://githubcard.com/YOUR_USERNAME.svg)](https://github.com/YOUR_USERNAME)

Step 3: Make the streak the focus (optional)

If you want the streak front and center:

1. Open the canvas editor at https://githubcard.com/ and pick a profile card.
2. Enter your username.
3. Drag in the Streak Stats widget and resize it as the main element.
4. Add supporting widgets if you like: Contributions Heatmap, Profile Stats, Language Donut.
5. Set one theme for the whole card, then export as SVG (or PNG for social posts and slides).

Saving and updating a custom design requires signing in with GitHub.

Things to know

• Freshness: cards use live GitHub data with caching, so changes can take up to about an hour to appear. Don't panic if today's commit doesn't show immediately.
• Cost: core features are free, per the site's FAQ.
• Repos too: the same pattern works for repositories: https://githubcard.com/OWNER/REPO.svg.

A note on streaks

Streaks are motivating, but they're not a measure of quality. Many solid engineers have gaps because they work in private repos or take weekends off. Treat a streak card as a small signal on your profile, not the headline. Pair it with pinned projects and a short line about what you build.

I build GitHubCard. If you try it, I'd genuinely like to hear what's missing.