Get Cloud Agent usage via API
Read token usage for a Cloud Agent with GET https://api.cursor.com/v1/agents/{id}/usage. Official reference: Cloud Agents API → Get Agent Usage.
The Cloud Agents API v1 is in public beta. Authenticate with Basic auth (API key as username, empty password) or Authorization: Bearer YOUR_API_KEY. Create a user key at Cursor Dashboard → API Keys, or use a service account key. Availability: Beta (all plans) per the API overview.
Token usage matches the tokenUsage shape reported by the team usage events endpoint.
Query parameters
| Parameter | Rules |
|---|---|
runId |
Optional. Scope the response to one run (run-…). Omit to return usage for every run on the agent. Unknown runId → 404 run_not_found. |
Request
# All runs on the agent
curl --request GET \
--url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage \
-u YOUR_API_KEY:
# A single run
curl --request GET \
--url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/usage?runId=run-00000000-0000-0000-0000-000000000001' \
-u YOUR_API_KEY:
Response shape
totalUsage sums the returned runs. runs lists per-run usage (one entry when runId is set).
Each run object includes:
| Field | Meaning |
|---|---|
id |
Run id (run-…) |
usageUuid |
Optional internal usage id; omitted when the run has no recorded usage yet |
usage.inputTokens |
Input tokens |
usage.outputTokens |
Output tokens |
usage.cacheWriteTokens |
Cache write tokens |
usage.cacheReadTokens |
Cache read tokens |
usage.totalTokens |
Sum of the four counts above |
Runs with no recorded usage report zeros across all fields. A run that has not produced usage yet still appears in runs so you can poll it.
{
"totalUsage": {
"inputTokens": 12480,
"outputTokens": 3110,
"cacheWriteTokens": 18200,
"cacheReadTokens": 42600,
"totalTokens": 76390
},
"runs": [
{
"id": "run-00000000-0000-0000-0000-000000000002",
"usageUuid": "00000000-0000-0000-0000-000000000002",
"usage": {
"inputTokens": 6320,
"outputTokens": 1450,
"cacheWriteTokens": 7100,
"cacheReadTokens": 21300,
"totalTokens": 36170
}
}
]
}