Build with your burn.

Endpoints

Production base URL: https://api.whoburnedmore.com. Send private keys as Authorization: Bearer $WBM_USAGE_KEY, never in a query string. Create and revoke keys in the embed studio. At most five keys per account, each valid for one year. These keys cannot submit, edit or delete usage.

Summary fields

• schemaVersion: 1. Future additions are additive; check this before depending on a different version.
• handle, visibility: account handle and public/owner read mode.
• period: today, week, 7d, 30d (default), year, all. Week starts Monday; year starts January 1, both through today in the account’s timezone. The studio defaults to today. from/to are inclusive YYYY-MM-DD dates. from is null for all time.
• timezoneOffsetMinutes: account’s last reported offset east of UTC; zero if unknown. Days follow the original submitting machine’s local calendar.
• totals: tokens, costUSD, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, activeDays. Tokens include all four token categories. Cost is estimated API value, not billed subscription spend.
• daily: ascending date, tokens, costUSD, with zero-filled inactive dates. All-time summaries show the last 30 days here; totals still cover all available history.
• highlights: calendar token totals for today, week, and year. activity: last 84 days of date/tokens for the heatmap. These are independent of the selected summary period and obey the same privacy rules.
• byTool/byModel: tool/model name, tokens and costUSD, largest token count first, for the selected period.
• generatedAt: response creation time. lastSyncedAt: last stored usage update or null. These timestamps are UTC ISO 8601.
• freshness: fresh within 24 hours; stale after 24 hours; never when there are no stored usage updates. Fresh does not guarantee every device or tool is connected.
• coverage: synced-history or limited-history. Summaries use at most the most recent 50,000 stored usage rows. The latter warns that older rows may be absent. Use owner entries to export the full history.

Exporting daily records

The entries response has schemaVersion, entries and nextCursor. Every entry contains id, date, tool, model, totalTokens, costUSD, all four token categories, pendingApproval and updatedAt. Pass cursor=nextCursor to get the next page; stop when it is null. Limits are 1–500, default 100. Cursor order is stable by record ID; do not interpret IDs as dates. Exports are live reads, so pause sync during a consistency-sensitive export.

Privacy and errors

Public reads require a listed public profile and omit pending-review days. Suppressed, blocked, deleted, private, and unknown accounts all return 404 with usage_unavailable. A launch gate also hides public usage, even with a signed-in cookie. Owner-key reads include private and pending data and always use Cache-Control: no-store.

400: invalid options; 401: invalid, expired or revoked key; 404: unavailable usage; 429: slow down; 503: temporary service failure. Public cards return a neutral 200 SVG when visibility is withdrawn, so an old image can be replaced. A service outage returns 503, never invented zero totals.

Read quota: 120 requests per minute per network address, shared across these endpoints. Respect Retry-After on 429, back off on 5xx, and poll no more than once per minute. The public JSON API allows cross-origin browser reads. Keep personal keys in trusted server-side integrations, even though bearer-authenticated CORS requests are supported.

Card options and caching

style: signature (default), activity, breakdown, heatmap, stats, compact, badge. theme: dark (default), light. accent: ember (default), mono (black & white), mint, violet. period: today, week, 7d, 30d (default), year, all. Unknown, duplicate or invalid options return 400. Use the web URL generated in the studio for your README. Image quotas are 120 requests per minute per network address and profile, so a shared image proxy does not combine unrelated profiles.

Images request cache revalidation on every read. Your machine normally syncs about every 15 minutes; GitHub’s image proxy can take longer to display changes. The badge omits the sync date for space, so use a larger card or JSON freshness when that matters. Historical cached copies cannot be recalled. See GitHub’s image-cache troubleshooting.