Skip to content
Skills Library
Data & analytics · Analysis

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.

Licence
MIT
Last repository change
24.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 24.08.2026, without references to retired models or APIs.

Licence

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

  1. Three rulers
  2. Hard rules
  3. Workflow
  4. Report language
  5. Endpoints
  6. Red flags
  7. More
Original SKILL.md headings · 146 lines, 1,030 words
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".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.