tokentracker API
tokentracker turns the token usage your AI coding tools already record into a public, queryable API. A small collector runs on each of your machines and uploads daily totals per tool and model. The API answers questions like how many tokens did I use this month, which models, which tools and which days, as JSON or CSV.
Reads are public and need no key. Base URL:
https://tokentracker.patrickbrown.dev/api/v1
Quickstart
curl https://tokentracker.patrickbrown.dev/api/v1/users/bicrick/stats?range=ytd
const res = await fetch('https://tokentracker.patrickbrown.dev/api/v1/users/bicrick/usage?range=30d&group=day');
const { totals, rows } = await res.json();
// rows: [{ period: "2026-10-20", tokens, input, output, reasoning, cacheRead, cacheWrite, responses }, ...]
Swap bicrick for your handle once you've installed the collector.
Install the collector
Needs Node 22.13+ on macOS, Linux or Windows.
npx github:bicrick/tokentracker init
- Finds the AI tools on this machine and shows what it found before anything is sent.
- You choose which tools to track.
- Creates your account (pick a handle, sign in by email) or signs this machine into an existing one.
- Uploads your history and turns on an hourly background sync (no admin rights).
On each additional machine, run the same command and choose Sign in with email. Totals from all machines combine.
Conventions
- Method: every endpoint is
GET. Responses are JSON unlessformat=csv. - Auth: none for reads. Profiles are public.
- CORS:
Access-Control-Allow-Origin: *, so you can call it from any browser page. - Caching: responses are cached at the edge for 5 minutes. Collectors sync hourly.
- Rate limit: 120 requests per minute per IP, cached responses excluded. Over the limit you get
429withRetry-After. - Tokens:
tokens = input + output + reasoning + cacheRead + cacheWrite.inputexcludes cached input.responsescounts model calls. - Dates:
YYYY-MM-DDdays in the collector's local time zone. - Every response echoes
handleand the appliedfilters.
Filters
Accepted by every endpoint below.
| Param | Values | Default |
|---|---|---|
range | all, ytd, Nd (e.g. 30d, 365d), or a year like 2026 | all |
from, to | YYYY-MM-DD, inclusive. Override range | |
tools | Comma-separated tool ids, e.g. claude-code,codex | all |
models | Comma-separated model ids, e.g. anthropic/claude-opus-5-5 | all |
format | csv on usage, models, tools, devices | json |
Profile
GET /api/v1/users/{handle}
A summary: all-time and this-year totals, tools, model and machine counts, first and last active day, last sync, and links to every resource.
Usage
GET /api/v1/users/{handle}/usage
Token usage over time.
| Param | Values |
|---|---|
group | day (default), week (ISO, starts Monday), month, year, total |
split | tool or model: adds split: { key: tokens } to each row |
fill | false to omit empty days (daily series are continuous by default) |
Returns { group, split, totals, rows: [{ period, tokens, input, output, reasoning, cacheRead, cacheWrite, responses, split? }] }.
Models
GET /api/v1/users/{handle}/models
One row per model and tool, sorted by tokens: { model, provider, name, tool, tokens, input, output, reasoning, cacheRead, cacheWrite, responses, share, firstUsed, lastUsed }. Cursor reports totals only, as cursor/all.
Tools
GET /api/v1/users/{handle}/tools
One row per tool: { tool, name, tokens, …, responses, share, models, firstUsed, lastUsed }.
Heatmap
GET /api/v1/users/{handle}/heatmap
A ready-to-render calendar grid. Colour levels are ranked among active days so one huge day doesn't wash out the rest.
| Param | Values |
|---|---|
range | year (default: this calendar year, padded to Dec 31), 365d, 90d, any Nd, or a year |
levels | 2–10 colour steps including empty (default 5) |
weekStart | sun (default) or mon |
tools | Filter to some tools |
Returns { range, levels, weekStart, total, max, activeDays, months: [{ label, week }], weeks: [[{ date, tokens, level } | null × 7], …] }. Days after today have tokens: null; cells outside the range are null.
Stats
GET /api/v1/users/{handle}/stats
Totals plus activeDays, firstDay, lastDay, busiestDay, longestStreak, currentStreak, averagePerActiveDay, today, thisMonth, topTool and topModel (by responses).
Devices
GET /api/v1/users/{handle}/devices
One row per machine: { device, tools, lastSync, tokens, …, firstUsed, lastUsed }.
Errors and limits
Errors use HTTP status codes and one shape:
{ "error": { "code": "bad_range", "message": "range must be all, ytd, Nd (e.g. 30d) or a year (e.g. 2026)" } }
| Status | Codes |
|---|---|
| 400 | bad_range, bad_date, bad_group, bad_split, bad_tools, bad_models, bad_levels, csv_unsupported |
| 404 | user_not_found, unknown_resource |
| 405 | method_not_allowed |
| 429 | rate_limited |
Reads are limited to 120 requests per minute per IP. Responses served from the edge cache don't count. Every response carries RateLimit-Limit and RateLimit-Remaining; a 429 includes Retry-After in seconds.
Recipe: a heatmap
const hm = await (await fetch(`${API}/users/you/heatmap?range=year`)).json();
grid.style.gridTemplateColumns = `repeat(${hm.weeks.length}, 1fr)`;
grid.innerHTML = hm.weeks.flat().map((d) =>
d ? `<i class="lvl-${d.level}" title="${d.date}: ${d.tokens ?? ''}"></i>` : '<i class="out"></i>'
).join('');
// CSS: .grid { display: grid; grid-auto-flow: column; grid-template-rows: repeat(7, 1fr); gap: 3px }
Recipe: a monthly chart by tool
const { rows } = await (await fetch(`${API}/users/you/usage?range=ytd&group=month&split=tool`)).json();
// rows[i] = { period: "2026-07", tokens, split: { "claude-code": 812345678, cursor: 123456789 } }
// Stack split values per bar; height = tokens / max(tokens).
Recipe: a model leaderboard
const { rows } = await (await fetch(`${API}/users/you/models?range=30d`)).json();
rows.filter((m) => m.model !== 'cursor/all')
.sort((a, b) => b.responses - a.responses)
.slice(0, 5);
Data sources
| Tool id | Tool | Read from |
|---|---|---|
claude-code | Claude Code | ~/.claude/projects |
codex | Codex CLI, IDE, app | ~/.codex/sessions |
opencode | OpenCode (incl. GitHub Copilot) | ~/.local/share/opencode/opencode*.db |
gemini-cli | Gemini CLI | ~/.gemini/tmp/*/chats |
copilot-cli | Copilot CLI | ~/.copilot/session-state |
deepseek-harness | DeepSeek Harness | ~/.dsh/sessions |
cline, roo-code, kilo-code | Cline, Roo Code, Kilo Code | Extension storage in VS Code, Cursor, Windsurf, VSCodium, Kiro |
cursor | Cursor | Your public cursor.com/@handle profile (totals only) |
Privacy
Only daily token counts per tool and model leave your machine: never prompts, code, file paths or API keys. The ingest endpoint rejects anything else. Run tokentrack sync --dry to see the exact payload.
Accounts
- Reading is public. Writing (uploads, settings) needs a machine key.
initsigns you in by email: click the link and the terminal finishes on its own. Each machine gets its own key, stored in~/.config/tokentrack/config.jsonand hashed on the server.- Settings: see and revoke machines, connect Cursor, delete your account.
CLI
tokentrack init | Guided setup |
tokentrack connect | Choose tools, add custom folders, connect Cursor |
tokentrack sync [--dry] [--full] | Upload now; --dry prints the payload |
tokentrack status | Account, machine, tools and recent syncs |
tokentrack install / uninstall | Background sync on or off |
tokentrack delete-account | Delete your account and data |
Self-hosting
Deploy the repo to Vercel with a Neon Postgres database, set TOKENTRACK_INGEST_KEYS, TOKENTRACK_ACCOUNT and CRON_SECRET, then run init and choose Use a key or my own server. The API is identical. Details on GitHub ↗
llms.txt and OpenAPI
- /llms.txt: a compact guide to this API for LLMs and agents.
- /openapi.json: OpenAPI 3.1 spec for code generation and tooling.
- /api/v1: a JSON index of every endpoint.