Get filtered usage events with the Organization API

Pull detailed usage events across every team linked to your organization with POST https://api.cursor.com/organizations/filtered-usage-events. Each event carries the same shape as the team route, plus an owning teamId. Official reference: Organization API → Get Usage Events.

Authenticate with an Organization API key (Basic auth, key as username, empty password). Usage routes need usage:* (or admin:*). Enterprise only. For a single team, use the team Admin API (Get filtered usage events).

Usage aggregates at the hourly level. Poll at most once per hour. Org usage routes share the 20 requests per minute rate limit.

Request

By default the response includes every team in the organization pool. Pass teamIds to restrict it.

curl -X POST https://api.cursor.com/organizations/filtered-usage-events \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "page": 1,
    "pageSize": 25
  }'

Restrict to specific linked teams:

curl -X POST https://api.cursor.com/organizations/filtered-usage-events \
  -u YOUR_ORGANIZATION_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "teamIds": [7, 8],
    "startDate": 1748411762359,
    "endDate": 1751003762359,
    "page": 1,
    "pageSize": 25
  }'

Field	Rules
organizationId	Required. Public org id. Must match the key’s organization
teamIds	Optional. Integer team ids linked to the org. Every entry must belong to the organization
startDate / endDate	Optional. Inclusive epoch milliseconds
userId	Optional. Numeric user id filter
email	Optional. User email filter
serviceAccountId	Optional. Service account id filter
page	Optional. 1-indexed. Default 1
pageSize	Optional. Default 10

Cost fields

• Sum chargedCents across events to reconcile with per-team usedCents from Get pooled usage. That total includes model cost plus the Cursor Token Rate when the request is eligible.
• 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.

Event fields (each usageEvents row)

Field	Meaning
teamId	Linked team that owns the event
timestamp	Epoch milliseconds as a string
userEmail	Requester email
serviceAccountId / serviceAccountName	Present for service-account events
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.

Pitfalls

• Body organizationId must match the Organization API key or the call is rejected.
• A teamIds entry outside the organization is rejected.
• Mint a key with usage:* or admin:* — members:* alone cannot call reporting routes.
• Team Admin API filters such as cloudAgentId, automationId, and hostingType are documented on the team route; use that endpoint when you need those filters on one team.