Estimated cost of a session and whether every turn reported it
Reads the session's estimated provider cost and token count over its lifetime, its cost and token limits, and its queued input against the per-session limit. The cost is the platform's estimate from the model calls it saw, not a bill. cost.complete: false means a turn is still open or ended without reporting, so the true total is unknown; do not read it as zero. budget_exceeded: true means either limit is reached: no new turn is dispatched, but input is still accepted and queued. It changes nothing.
Scope: sessions:read (API key or cookie session).
AuthorizationBearer <token>For servers and scripts: an API key sent as an HTTP bearer token, Bearer <key>. It holds exactly the scopes it was issued with; a key issued before scopes existed holds none. It never needs the CSRF header, and it cannot manage agents, members, teams or API keys. Issue one in the web console under Settings → API keys; each operation names the scope it needs.
Scope: sessions:read
id*stringThe session's id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidThe session's usage as of refreshed_at.
application/json- response
session_id*string^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidperiod*stringrefreshed_at*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timecost*cost_limit_usd*|nulltoken_count*integer0 <= value <= 9007199254740991token_limit*|nullbudget_exceeded*booleanqueued_input_count*integer0 <= value <= 9007199254740991queued_input_limit*integer0 <= value <= 9007199254740991curl -X GET 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/usage'{ "session_id": "0f8b6a52-3d1e-4c7a-9b2f-5e6d7c8a9b01", "period": "session_lifetime", "refreshed_at": "2026-10-11T08:15:43Z", "cost": { "amount_usd": "0.4231", "kind": "estimated", "source": "provider_usage", "completeness_scope": "turn_reports", "complete": false, "reported_turn_count": 2, "unreported_turn_count": 0, "open_turn_count": 1 }, "cost_limit_usd": "20", "token_count": 182450, "token_limit": null, "budget_exceeded": false, "queued_input_count": 1, "queued_input_limit": 20}