Get filtered usage events with the Admin API

Fetch granular usage events (model, tokens, costs, cloud agent / automation attribution) with POST https://api.cursor.com/teams/filtered-usage-events. Official reference: Admin API → Get Usage Events Data.

Authenticate with a team Admin API key (Basic auth, key as username, empty password). Data is aggregated at the hourly level — poll at most once per hour. Rate limit: 60 requests per minute per team.

Basic filtered request

startDate and endDate are inclusive epoch milliseconds.

curl -X POST https://api.cursor.com/teams/filtered-usage-events \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "email": "developer@company.com",
    "page": 1,
    "pageSize": 25
  }'

Field	Rules
startDate / endDate	Epoch ms, inclusive. For non-overlapping daily windows, end the prior day at …T23:59:59.999Z
userId	Optional. Numeric user id filter
email	Optional. User email filter
serviceAccountId	Optional. Service account id
cloudAgentId	Optional. One cloud agent run id, or * for all cloud agent runs
automationId	Optional. One automation UUID, or * for all automations
hostingType	Optional. CLOUD, SELF_HOSTED, SELF_HOSTED_POOL, or SELF_HOSTED_MACHINE. Unknown value → 400
page	Optional. Default 1
pageSize	Optional. Default 100, maximum 1000

Multiple filters combine with AND. hostingType isolates inference spend for self-hosted vs Cursor-hosted agents; self-hosted compute is never metered by Cursor.

Cost fields

• Sum chargedCents across events to reconcile with /teams/spend / dashboard totals (model cost + Cursor Token Rate when eligible). Works for token-based and request-based plans.
• cursorTokenFee is the Cursor Token Rate in cents. Present only when the rate applies to a third-party model request (including Auto routing to a third-party model). First-party Cursor models such as Grok and Composer, and request-based enterprise accounts, do not include this fee.
• For billable request units under older request-based pricing, sum requestsCosts (also the recommended substitute for the raw *Reqs counters on daily-usage-data).

Event fields (each usageEvents row)

Field	Meaning
timestamp	Epoch milliseconds as a string
userEmail	Requester email
serviceAccountId / serviceAccountName	Present for service-account events
cloudAgentId / automationId	Present when attributed to a cloud agent run or automation
conversationId	Agent session id when present; join key with sources such as the AI Code Tracking API
model	Model id
kind	Billing category (e.g. Usage-based, Included in Business)
maxMode	Whether Max Mode was on
requestsCosts	Cost in request units
isTokenBasedCall / isChargeable / isHeadless	Billing / headless flags
tokenUsage	Present when isTokenBasedCall is true — inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, totalCents, optional discountPercentOff
chargedCents	Total charged cents for the event
cursorTokenFee	Optional Cursor Token Rate cents

Response also includes totalUsageEventsCount, pagination (numPages, currentPage, pageSize, hasNextPage, hasPreviousPage), and period.

Filter examples from the docs

Service account:

curl -X POST https://api.cursor.com/teams/filtered-usage-events \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "serviceAccountId": "sa_abc123",
    "page": 1,
    "pageSize": 10
  }'

Automation UUID (attribution works for automations run as a user or a service account) — sum chargedCents on matching rows for that automation's cost:

curl -X POST https://api.cursor.com/teams/filtered-usage-events \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "automationId": "7fc64f90-6d7a-4a5d-91b1-bd1f529a85dd",
    "page": 1,
    "pageSize": 100
  }'

Self-hosted inference:

curl -X POST https://api.cursor.com/teams/filtered-usage-events \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "hostingType": "SELF_HOSTED",
    "page": 1,
    "pageSize": 10
  }'

Pitfalls

• Typo in hostingType — returns 400, not an empty list
• Exclusive end bounds that drop midnight events — both ends are inclusive; use last-ms-of-day for daily ETL windows
• Expecting cursorTokenFee on Grok / Composer / request-based enterprise traffic — docs say those paths omit the fee
• Polling more than once per hour — hourly aggregation; stay within 60/min when paging large ranges