1. The Core Architecture of GitHub Readme Stats
When you embed a stats card in your README, your browser loads an SVG image hosted on Vercel. The server queries GitHub’s GraphQL API in real time to aggregate your repository stars, total commits, active pull requests, and verified issues. It then dynamically renders a crisp SVG with scalable vector text and icons.
The project provides two primary API endpoints:
/api: Main profile statistics card (stars, commits, PRs, issues, contributions)./api/top-langs: Breakdown of programming languages used across your public repositories.
2. Complete Query Parameter Reference
Fine-tune the output using query parameters appended to the endpoint URL:
| Parameter | Accepted Values | Description |
|---|---|---|
show_icons | true, false | Displays vector icons alongside each statistic. Recommended: true. |
include_all_commits | true, false | Counts all lifetime commits across all years instead of the current calendar year. |
count_private | true, false | Includes commits from private repositories (requires self-hosted instance with PAT). |
hide | stars,prs,issues,contribs | Comma-separated list of metrics to hide from the card. |
hide_border | true, false | Removes the outer rectangular border for a seamless card-less look. |
border_radius | 0 to 20 | Controls border curvature (e.g. border_radius=12 matches modern UI). |
cache_seconds | 1800 to 86400 | Critical: Sets server cache TTL to prevent rate limiting. |
3. Recommended Themes & Custom Hex Palettes
Rather than sticking with the stark default white card, choose a curated theme that matches your personal brand:
theme=tokyonight: Sleek indigo background with cyan and magenta accents.theme=nord: Cool Scandinavian arctic blues and soft white typography.theme=radical: High-contrast cyberpunk palette with electric neon hues.theme=dracula: Classic vampire dark theme beloved by terminal enthusiasts.
Applying Custom Colors Manually
You can override individual theme colors by specifying 6-character hex codes (without the #):
https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&bg_color=0f141c&title_color=cc785c&text_color=94a3b8&icon_color=e8a55a&border_color=1e293b&show_icons=true
4. Fixing the "Rate Limit Exceeded" Error
The Problem:
The public demo instance at github-readme-stats.vercel.app serves millions of daily requests. When GitHub’s GraphQL hourly rate limit is exhausted, cards display an ugly error banner: "Something went wrong: rate limit exceeded".
The Solution:
Step 1: Always specify caching. Add &cache_seconds=86400 to your card URL. This instructs Vercel’s Edge Network to cache the generated SVG for 24 hours instead of hammering the GitHub API on every pageview.
Step 2: One-click self-host. Fork the anuraghazra/github-readme-stats repository, deploy it to your own free Vercel account, and add a Personal Access Token (PAT) with repo permissions in your Vercel Environment Variables. Your cards will have 5,000 personal requests per hour and 100% uptime.
5. Side-by-Side Responsive Layout Snippet
To align the Main Stats card and the Top Languages card side-by-side without horizontal mobile overflow, use a centered paragraph wrapper:
<p align="center"> <img src="https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&show_icons=true&theme=tokyonight&cache_seconds=86400" alt="Stats" /> <img src="https://github-readme-stats.vercel.app/api/top-langs/?username=YOUR_HANDLE&layout=compact&theme=tokyonight&cache_seconds=86400&hide=html,css" alt="Top Languages" /> </p>
Configure GitHub Stats in ProfileCrest
Test themes, toggle icons, exclude languages, and copy pre-cached URLs with ProfileCrest’s real-time builder.
🚀 Launch ProfileCrest Generator