Command overview
beacon endpoint cursor collects telemetry from Cursor that its hooks cannot see. sync reads the conversation records Cursor commits on this machine. usage sync reads Cursor’s per-request token usage and charges from the Cursor Admin API, because no Cursor hook or local record carries a token count.
Command syntax
Every event from these commands is marked
harness.collection_method=poll. Beacon reads what Cursor recorded after the fact, so neither path can hold, approve, deny, or delay a tool call, and neither synthesizes approval events.
Session sync
Cursor keeps Composer conversations in its global storage database (state.vscdb) and agent transcripts under ~/.cursor/projects. sync reads those committed records and writes prompts, assistant text, tool and command activity, file activity where the record names a path, and session metadata. Reading is local and offline.
Sweep once
Preview without writing anything
Sweep continuously
--print neither writes the runtime log nor advances the cursor, so running it twice shows the same events. Nothing sweeps on its own: run sync on a schedule, or leave --watch running in the account that owns the Cursor data. beacon endpoint install runs the same sweep once for the last 30 days.
Show Cursor's stores and collection progress
Session sync flags
Bothsync and status accept:
sync also accepts:
Token usage from the Cursor Admin API
Cursor’s hooks and local records carry no token counts. The Cursor Admin API does: it reports every model request a team member made with its input, output and cache tokens and what Cursor charged for it.usage sync reads those events and writes one token.usage event per request, so beacon token-usage and the dashboard token view include Cursor.
This is the one Cursor command that uses the network. It calls https://api.cursor.com only when you run it; hooks and scheduled Beacon jobs never do.
1
Create an Admin API key
In the Cursor dashboard, open Settings > Advanced > Admin API Keys. Only team admins can create one.
2
Put it in the environment and sync
Sync this machine's Cursor usage
--api-key-env names a different variable.
Whose usage is collected
An admin key can read the whole team, so the default is deliberately narrow: the Cursor account signed in on this machine, read from Cursor’s local storage. If no account is signed in, the sync stops and asks you to choose. Choose at most one of:
Each choice keeps its own cursor, because what has been collected for one member says nothing about another.
What is recorded
Cursor’s token price is kept under
raw.cursor and not promoted to cost_usd, because a request included in a plan has a token price but no charge, and summing token prices would report a bill nobody received. Requests billed per request rather than by token, which carry neither tokens nor a charge, are not written.
No session is set. The Admin API reports requests per team member, not per conversation, and nothing in an event names the Composer it came from, so Beacon does not guess one from timing.
Windows and repeats
The first sync collects the last 7 days;--since reaches further back (YYYY-MM-DD or RFC 3339), and long ranges are fetched 30 days at a time. Each later sync starts from the last one and re-reads the 48 hours behind it (--lookback), because Cursor posts some usage late. The API gives events no id, so Beacon names each one by a fingerprint of everything the API says about it and writes only fingerprints it has not written before. Running the sync twice, or overlapping its windows, never counts a request twice. A sync that fails partway keeps what it wrote, and the retry writes the rest.
The state file holds fingerprints and timestamps, never the key.
Preview a month of team usage without writing it
Show the usage collector's progress
Usage flags
Bothusage sync and usage status accept:
usage sync also accepts:
Related
Cursor
Hooks, coverage, and what each Cursor path records.
beacon token-usage
Report token usage and cost from the runtime log.