AI Usage API

These endpoints expose usage information that an authenticated client can act on. Provider diagnostics and prompt-cache internals are operational implementation details and are intentionally not part of the public documentation.

Endpoints

Method	Path	Purpose	Authentication
GET	/ai/operations/rate-limit	Read the current account's AI request allowance.	JWT + AI entitlement
GET	/ai/operations/sessions/:sessionId/usage	Read token usage for an accessible AI session.	JWT + AI entitlement

GET /ai/operations/rate-limit

curl --fail-with-body "$BASE_URL/ai/operations/rate-limit" \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "data": {
    "limit": 60,
    "remaining": 42,
    "resetsAt": "2026-10-01T10:01:00.000Z",
    "scope": "account"
  }
}

Limits depend on the authenticated account and can change. Use the returned values rather than hard-coding a plan threshold.

GET /ai/operations/sessions/:sessionId/usage

Use a session id returned by the Sessions API.

curl --fail-with-body "$BASE_URL/ai/operations/sessions/$SESSION_ID/usage" \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "data": {
    "sessionId": "<session-uuid>",
    "totalInputTokens": 4250,
    "totalOutputTokens": 1823,
    "totalTokens": 6073,
    "estimatedCostUsd": 0.018,
    "runCount": 5
  }
}

estimatedCostUsd can be null when the service cannot calculate a public estimate.

Errors

Status	Meaning
401	The access token is missing or invalid.
403	The account lacks the required entitlement or session access.
404	The session does not exist or is not visible to the caller.
429	The caller exceeded an applicable request limit.

Errors use the standard response envelope.