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
  1. Finds the AI tools on this machine and shows what it found before anything is sent.
  2. You choose which tools to track.
  3. Creates your account (pick a handle, sign in by email) or signs this machine into an existing one.
  4. 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 unless format=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 429 with Retry-After.
  • Tokens: tokens = input + output + reasoning + cacheRead + cacheWrite. input excludes cached input. responses counts model calls.
  • Dates: YYYY-MM-DD days in the collector's local time zone.
  • Every response echoes handle and the applied filters.

Filters

Accepted by every endpoint below.

ParamValuesDefault
rangeall, ytd, Nd (e.g. 30d, 365d), or a year like 2026all
from, toYYYY-MM-DD, inclusive. Override range
toolsComma-separated tool ids, e.g. claude-code,codexall
modelsComma-separated model ids, e.g. anthropic/claude-opus-5-5all
formatcsv on usage, models, tools, devicesjson

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.

ParamValues
groupday (default), week (ISO, starts Monday), month, year, total
splittool or model: adds split: { key: tokens } to each row
fillfalse 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.

ParamValues
rangeyear (default: this calendar year, padded to Dec 31), 365d, 90d, any Nd, or a year
levels2–10 colour steps including empty (default 5)
weekStartsun (default) or mon
toolsFilter 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)" } }
StatusCodes
400bad_range, bad_date, bad_group, bad_split, bad_tools, bad_models, bad_levels, csv_unsupported
404user_not_found, unknown_resource
405method_not_allowed
429rate_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 idToolRead from
claude-codeClaude Code~/.claude/projects
codexCodex CLI, IDE, app~/.codex/sessions
opencodeOpenCode (incl. GitHub Copilot)~/.local/share/opencode/opencode*.db
gemini-cliGemini CLI~/.gemini/tmp/*/chats
copilot-cliCopilot CLI~/.copilot/session-state
deepseek-harnessDeepSeek Harness~/.dsh/sessions
cline, roo-code, kilo-codeCline, Roo Code, Kilo CodeExtension storage in VS Code, Cursor, Windsurf, VSCodium, Kiro
cursorCursorYour 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.
  • init signs 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.json and hashed on the server.
  • Settings: see and revoke machines, connect Cursor, delete your account.

CLI

tokentrack initGuided setup
tokentrack connectChoose tools, add custom folders, connect Cursor
tokentrack sync [--dry] [--full]Upload now; --dry prints the payload
tokentrack statusAccount, machine, tools and recent syncs
tokentrack install / uninstallBackground sync on or off
tokentrack delete-accountDelete 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.