GH-STATS / DOCUMENTATION

From API to README.
In a few lines.

Every card is a lightweight SVG image. Use the card studio → to build visually, or compose an API URL yourself. The hosted service needs no signup or personal token.

Your first card

Replace YOUR_USERNAME and paste this into your GitHub profile’s README.md:

![GitHub overview](https://gh-stats-plum-five.vercel.app/api/stats?username=YOUR_USERNAME&theme=dark)

Match light and dark appearance

GitHub’s image proxy does not reliably communicate a reader’s theme to an API. Use two explicit image sources:

<picture>
  <source media="(prefers-color-scheme: dark)"
    srcset="https://gh-stats-plum-five.vercel.app/api/stats?username=YOUR_USERNAME&amp;theme=dark" />
  <img src="https://gh-stats-plum-five.vercel.app/api/stats?username=YOUR_USERNAME&amp;theme=light"
    alt="My GitHub overview" />
</picture>

Nine cards. One simple API.

Endpoint	What it shows
`/api/stats`	Your open-source story, in numbers.
`/api/languages`	A colorful breakdown of your stack.
`/api/streak`	Show up. Build things. Keep going.
`/api/impact`	A year of contributions at a glance.
`/api/repos`	Put your most-loved projects first.
`/api/focus`	The languages behind your recent repositories.
`/api/pin`	Give one great project the spotlight.
`/api/gist`	Small snippets. Big ideas.
`/api/wakatime`	Your publicly shared coding activity.

Most cards accept username. Pinned repositories use repo=owner/name; gists use id=GIST_ID. WakaTime uses a WakaTime username with publicly shared statistics.

https://gh-stats-plum-five.vercel.app/api/pin?repo=SaumilP/gh-stats&theme=nord
https://gh-stats-plum-five.vercel.app/api/languages?username=octocat&layout=donut
https://gh-stats-plum-five.vercel.app/api/stats?username=octocat&format=json

What the numbers mean

Stars and forks cover up to 500 recently updated public repositories. Larger profiles are sampled; stats JSON includes sampled and repositoryLimit.
Contributions and streaks cover GitHub’s rolling past-year calendar. Use commits_year=2025 for a specific year in the stats endpoint. All-time commit aggregation is not supported.
Language primary mode weights the main language of recent repositories by stars. Bytes mode inspects up to 10 selected public repositories and has a higher upstream cost.
Focus is a repository-language distribution, not a commit count or a measurement of time spent.
WakaTime shows the requested public account, never the deployment owner’s private data.

A few personal touches

Parameter	Usage
`theme`	A named theme, e.g. dark, nord, radical
`custom_title`	A short card title
`title_color / text_color`	Hex colors, without the #
`bg_color / border_color`	Background and border overrides
`hide_border`	true to remove the card border
`border_radius`	Corner radius from 0 to 40
`layout`	Language/WakaTime: normal, compact, donut, donut-vertical, pie
`format`	svg (default) or json
`count / sort`	Repositories: 1–10; stars, forks, or updated

Existing advanced renderer parameters remain supported where applicable. The studio exposes commonly useful controls and generates correctly encoded URLs.

Find your palette.

Select a theme to open it in the studio. These colors come directly from the API’s theme registry.

Daily updates. Fewer moving parts.

GitHub data is cached independently of SVG styling for 24 hours. A new theme reuses the same snapshot. Refreshes happen on demand after expiry, so unused profiles consume no scheduled compute.

Vercel’s CDN serves rendered cards. Origin responses carry a TTL based on the underlying snapshot’s age.
During temporary provider failures, snapshots can be reused up to a maximum total age of seven days. Stale responses use a shorter cache window.
X-Card-Status reports fresh, stale, or error. X-Data-Updated-At records the oldest underlying snapshot used.
Public refresh, cacheSeconds, and cache_seconds parameters do not override the hosted daily-data policy.
GitHub’s own image proxy may retain an embed beyond the origin’s update time. A browser refresh cannot force that proxy to refresh.

Your infrastructure. Your cards.

Deploy this Next.js project on Vercel with Node.js 24. Set these server-side variables:

GITHUB_TOKEN=your_public_data_token
KV_REST_API_URL=your_upstash_rest_url
KV_REST_API_TOKEN=your_upstash_rest_token
NEXT_PUBLIC_SITE_URL=https://your-deployment.vercel.app

Use a GitHub token with only the access needed for public data. Never use a NEXT_PUBLIC_ prefix for secrets. Upstash’s UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN names are also supported.

Without a shared cache, a bounded per-instance cache keeps local development functional, but cannot deduplicate work across Vercel instances. The homepage and examples are static and need no token.

Optional static exports

The pregeneration script can update selected cards daily in a public repository. It validates all responses before replacing existing files, and rejects SVG error cards. See the README for configuration.

When something looks off

Card shows an error: verify the username, repository, or gist is public. The studio offers a retry without bypassing the cache.
Streak is unavailable: the service needs a valid server-side GitHub token for GraphQL, or a previously cached snapshot.
Stats look old: check X-Data-Updated-At. Normal updates are daily; stale snapshots are used only within the retention window.
Self-hosted service is degraded: inspect /api/health for token, cache, and quota status. Match X-Request-Id with Vercel function logs.

Found a bug? Open an issue → Include the endpoint, approximate time, and request ID. Keep credentials out of reports.

From API to README.In a few lines.