cursor-usage
/cursor-usage
Use when the user invokes /cursor-usage, or asks which Cursor chats burned the most tokens or dollars this cycle, how much Ultra/Pro quota is left vs OpenUsage or Settings → Plan & Usage, or to rebuild the Cursor usage canvas. Not for Teams Admin API, Stripe CSV exports, or editing OpenUsage.app.
- Author
- chocolatemale ↗
- Repository
- cursor-usage ↗
- Licence
- MIT
- Last repository change
- 24.08.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 24.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when the user invokes /cursor-usage, or asks which Cursor chats burned the most tokens or dollars this cycle, how much Ultra/Pro quota is left vs OpenUsage or Settings → Plan & Usage, or to rebuild the Cursor usage canvas. Not for Teams Admin API, Stripe CSV exports, or editing OpenUsage.app.
Original author description
Use when the user invokes /cursor-usage, or asks which Cursor chats burned the most tokens or dollars this cycle, how much Ultra/Pro quota is left vs OpenUsage or Settings → Plan & Usage, or to rebuild the Cursor usage canvas. Not for Teams Admin API, Stripe CSV exports, or editing OpenUsage.app.
How it works
- Three rulers
- Hard rules
- Workflow
- Report language
- Endpoints
- Red flags
- More
SKILL.md preview
---
name: cursor-usage
description: >-
Use when the user invokes /cursor-usage, or asks which Cursor chats burned
the most tokens or dollars this cycle, how much Ultra/Pro quota is left vs
OpenUsage or Settings → Plan & Usage, or to rebuild the Cursor usage canvas.
Not for Teams Admin API, Stripe CSV exports, or editing OpenUsage.app.
disable-model-invocation: true
---
# cursor-usage
Local Cursor session → unofficial dashboard APIs → a **canvas usage report**.
Three rulers live in the same payload. Mixing them once makes the report wrong.
**REQUIRED SUB-SKILL:** Read the canvas skill (`~/.cursor/skills-cursor/canvas/SKILL.md`) before writing the canvas.
## Three rulers
| Ruler | Fields | Answers | Does not answer |
|---|---|---|---|
| Quota bars | `individualUsage.plan.totalPercentUsed` / `autoPercentUsed` / `apiPercentUsed`, denominator always **100** | How much allowance is left. Same algorithm as OpenUsage and Settings | How many dollars were spent |
| Included $ | `plan.used` / `plan.limit` / `plan-info.includedAmountCents`, **cents** | Whether the plan SKU (Ultra: $400 Other Models) has been booked full | The progress bars, the Stripe bill |
| Event list price | Per-event `chargedCents` (or `tokenUsage.totalCents`) | Which chat / model is expensive | Remaining quota, card charges |
`displayMessage: "You've hit your usage limit"` follows included $. `used` **caps at `limit`**. Cap ≠ quota bars full. OpenUsage personal plans **do not** draw `used/limit`.
Settings: Cursor Models ≈ Auto. Other Models ≈ API.
## Hard rules
1. **Never print, file, or paste the session token.** Script stdout: counts and paths only. No email, no display name, no home path.
2. **Quota bars use `*PercentUsed` only.** Do not draw `plan.used/limit` as "included $ exhausted".
3. **`chargedCents` totals are not the Stripe bill.** If on-demand is off, overage is $0. Subscription price is `plan-info.price`.
4. **Do not publish the inferred $2500 as an official cap.** See [pitfalls.md](pitfalls.md). Mention it only if asked.
5. **POST bodies must not include `userId` or `teamId: 0`.** Those 500. Use `{}` or dates only.
6. **Use built-in `PieChart`.** Do not hand-roll an SVG donut to put `$` in the hole. Put dollars on `Stat` cards and slice `label`s.
7. **Date the report from actual event min/max.** A "last 30 days" request often returns only the **current billing cycle**.
8. **Canvas copy defaults to English.** Include an EN | 中文 toggle. See Report language.
## Workflow
```
Task Progress:
- [ ] Run scripts/fetch_cursor_usage.py
- [ ] Check the three rulers against OpenUsage / Settings
- [ ] Read the canvas skill; write canvases/cursor-usage.canvas.tsx
- [ ] Chat: remaining quota first, then list price; link the canvas
```
### 1. Fetch
```bash
python3 ~/.agents/skills/cursor-usage/scripts/fetch_cursor_usage.py
```
Read `/tmp/cursor-usage/report.json`. On failure, use `NO_SESSION` / the HTTP status. Do not dump the cookie.
Auth order (already in the script): `$CURSOR_SESSION_TOKEN` → Keychain `cursor-access-token` → `state.vscdb` key `cursorAuth/accessToken`. Cookie name: `WorkosCursorSessionToken`. POSTs need `Origin: https://cursor.com`.
### 2. Pools vs products
**Auto / Cursor Models:** `cursor-grok*`, `grok-*`, `composer*`, `vega*`, `default`. Grok Bot events are Grok, so they count as Auto.
**API / Other Models:** `claude*`, `gpt*`, `gemini*`, other third-party models.
**Product (where the chat ran, not the pool):**
- `cloudAgentId` or `isHeadless` → Cloud Agent
- Matched Grok Bot agent list → Grok Bot
- Else → Cursor IDE
Official aggregates rename Grok Bot to `sand-default` / `sand-automation`. Event `model` stays `cursor-grok-*`. Rank chats from events.
### 3. Titles
- Cursor: `~/.cursor/projects/*/agent-transcripts/<id>/*.jsonl` (roll subagents into the parent)
- Grok Bot: `~/Library/Application Support/Grok Bot/sand-client-persistence/*.blob` rows
- Cloud: `state.vscdb` key `cloudAgentRepository.agents*`
If nothing matches: `Untitled chat` + 8-char id. Do not invent a title.
### 4. Canvas
Path: `~/.cursor/projects/<workspace>/canvases/cursor-usage.canvas.tsx` (stable name, overwrite). Import only `cursor/canvas`. Inline data. No `fetch()`.
**Required order:**
1. Title + real event window + reset date + **EN | 中文** toggle (`useCanvasState("lang", "en")`)
2. Four `Stat`s: **list-price total**, **Auto list price**, **API list price**, **Stripe overage** ($0 if on-demand off). Quota percents must not replace these
3. Three `UsageBar`s: Total / Auto / API from `*PercentUsed`
4. Callout: list price ≠ quota bars ≠ Stripe
5. Auto vs API `PieChart donut` + caption for **that** chart. Default slice colors
6. Per-model table: pool, model, list price, requests, share
7. Top 20 stacked bars: custom `ModelStackChart` (built-in stacked `BarChart` tooltips list $0 series). 12px source icon on each name. Hover shows one segment. Total on the right
8. Product `PieChart donut` with tones `warning` / `danger` / `neutral` (IDE / Grok / Cloud)
9. Detail table
10. Cycle pills: plan, three percents, on-demand flag
**Do not:**
- Hand-roll a donut to fix the center `$`
- Drop the list-price `Stat`s after adding quota bars
- Pair a product pie with "how to read the bars" as if they were siblings
- Use gradients, emoji, box-shadows, or rainbow color
Link the canvas with its absolute path. If it is the workspace's first canvas, say what a canvas is.
### 5. Chat
Lead with remaining quota, then list-price total and the Auto/API split, then the most expensive chats. Link the canvas. Do not paste a second markdown table.
## Report language
Default: **English**.
Store chrome in a `COPY` map (`en` / `zh`). Toggle with `useCanvasState("lang", "en")` in the top-right. Task titles stay as stored (do not translate the user's chat names).
```tsx
const [lang, setLang] = useCanvasState<"en" | "zh">("lang", "en");
const t = COPY[lang];
```
Chat may follow the user's language. The canvas still opens in English until they switch.
## Endpoints
| Need | Request |
|---|---|
| Account | `GET /api/auth/me` |
| Quota + included $ | `GET /api/usage-summary` |
| Same quota (cycle) | `POST /api/dashboard/get-current-period-usage` `{}` |
| Events (paged) | `POST /api/dashboard/get-filtered-usage-events` `{startDate,endDate,page,pageSize:1000}` |
| Model rollup | `POST /api/dashboard/get-aggregated-usage-events` `{startDate,endDate}` |
| Plan SKU | `POST /api/dashboard/get-plan-info` `{}` |
| On-demand | `POST /api/dashboard/get-hard-limit` `{}` |
| Grok Bot weekly pool | `POST /api/dashboard/get-sand-usage-status` `{}` |
No official personal usage API. OpenUsage / CodexBar / tokscale hit the same unofficial dashboard. OpenUsage's primary path is `GetCurrentPeriodUsage` on `api2.cursor.sh`; mapping is still `*PercentUsed` / 100.
## Red flags
- About to write "quota exhausted" because `used == limit` (e.g. 40000 cents on Ultra)
- About to call a list-price total "this month's bill"
- About to hand-roll a donut so the hole can show `$`
- Title says "last 30 days" but events start on cycle day 1
- POST includes `teamId: 0`
- JWT or `WorkosCursorSessionToken` appears in debug output
- Canvas chrome is Chinese-only with no toggle
Any of these: stop. Return to the three rulers.
## More
Field traps, the inferred Total denominator, OpenUsage mapping: [pitfalls.md](pitfalls.md).
Files in this package (5)
- .gitignore 1 KB
- LICENSE 1 KB
- README.md 4 KB
- SKILL.md 7 KB
- pitfalls.md 4 KB
Versions
The database has no other skills named cursor-usage.
Database snapshot: 13.11.2026 · package version 4fade4d261b9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100cursor-usage-analytics
Track and analyze Cursor usage metrics. Triggers on "cursor analytics", "cursor usage", "cursor metrics", "cursor reporting", "cursor dashboard". Use when working with cursor usage analytics functionality. Trigger with phrases like "cursor usage analytics", "cursor analytics", "cursor". - 100cursor-usage-analytics
Track and analyze Cursor usage metrics via admin dashboard: requests, model usage, team productivity, and cost optimization. Triggers on "cursor analytics", "cursor usage", "cursor metrics", "cursor reporting", "cursor dashboard", "cursor ROI". - 100cursor-compliance-audit
Execute compliance and security auditing for Cursor usage. Triggers on "cursor compliance", "cursor audit", "cursor security review", "cursor soc2", "cursor gdpr". Use when analyzing or auditing cursor compliance audit. Trigger with phrases like "cursor compliance audit", "cursor audit", "cursor". - 100cursor-team-setup
Set up Cursor for teams: plan selection, member management, shared rules, admin dashboard, and onboarding. Triggers on "cursor team", "cursor organization", "cursor business", "cursor enterprise setup", "cursor admin".