CostWatch now serves a public AWS cost badge for GitHub READMEs
One thing I've seen on self-hosted project READMEs: a live "build passing" badge, a coverage percentage, sometimes a deployment status. What you almost never see is cost visibility — which is odd given that runaway AWS spend is the thing most likely to kill a side project or surprise a team at the end of the month.
CostWatch now has a public badge endpoint you can embed anywhere that renders an image.
The badge
GET /badge/{user_id} returns a shields.io-compatible SVG. It shows your month-to-date AWS cost and updates every time CostWatch runs its cost sync (currently every 6 hours).
Color coding:
- Green — spend is tracking normally relative to your configured budget
- Yellow — at or above 80% of monthly budget, or a significant spike detected week-over-week
- Red — over budget
The label is fixed ("AWS cost") and the value is your MTD spend rounded to two decimal places: $142.08.
Embed it in a README:
Or link it through to your CostWatch dashboard:
[](https://costwatch.app/dashboard)Opt-in, not on by default
This is the part I thought hardest about. AWS costs are sensitive data. If the badge were public by default, users would accidentally expose spend figures they didn't intend to share — and once a badge is embedded somewhere, it's not obvious it's leaking live financial data.
The endpoint returns a 404 for any user who hasn't enabled it. To enable:
POST /account/badge
Authorization: Bearer <token>Response includes your embed markdown ready to paste:
{
"enabled": true,
"badge_url": "https://costwatch.app/badge/user123",
"embed_markdown": ""
}To disable, DELETE /account/badge. The endpoint immediately starts returning 404 and any cached badge SVGs in CDNs or GitHub's image proxy will show stale data until they expire — which is the same tradeoff shields.io itself makes.
Use cases
Personal project README — useful signal for anyone who forks your repo or is evaluating whether to self-host your stack. "This thing costs me $8/month" is better documentation than nothing.
Company status page — a devops team embedding this on an internal status board gets a live cost number without building a separate integration.
Devops dashboard — Grafana and similar tools can render image panels. The badge URL is a valid image source.
What the badge can't do
It's a snapshot, not a trend. It shows MTD spend, not whether that spend is accelerating. For trend data, the dashboard is the right place — the badge is just the "is something on fire right now" signal you can see without logging in.
If you want the yellow/red state to trigger something rather than just display, the existing webhook and alert channels are still the right tool. The badge is read-only and pull-based — you check it when you look at the README, not when CostWatch decides you should know.