Documentation menu
Analytics

Aggregate token usage across authorized Projects

GET /api/v1/analytics/token-usage

Specify projectId for a single Project. A Session must specify organizationId to aggregate across Projects. Organization-scoped credentials may omit both. Includes only Projects with whole-Project analytics permission and a live permitted role. Environment-only or Agent-only credentials use the Environment analytics endpoint. Filters apply before aggregation and pagination. Token totals are exact decimal strings; missing counters are reported separately. No historical backfill or pricing is inferred.

Parameters

query

NameTypeRequiredDescription
projectIdstringoptionalFilters results to the specified Project. Applies to Aggregate token usage across authorized Projects.
organizationIdstringoptionalSelects the organization for the aggregate report. Required for sessions when projectId is omitted. Omit when selecting a single Project.
fromstringrequiredSets the inclusive start of the Analytics time window. Applies to Aggregate token usage across authorized Projects.
tostringrequiredSets the exclusive end of the Analytics time window. Applies to Aggregate token usage across authorized Projects.
provider"anthropic" | "google" | "openai" | "azure-openai" | "amazon-bedrock" | "google-vertex" | "deepseek" | "fireworks"optionalFilters recorded invocations to the exact provider.
requestedModelstringoptionalFilters recorded invocations to the exact requested model identifier.
groupBy"project" | "environment" | "model" | "provider" | "none"optionalGroups authorized Projects by Project alone, by Environment, by provider, or by requested/response model. None returns a combined total.
granularity"hour" | "day" | "none"optionalUses UTC hourly or daily buckets, or none for the entire interval.
limitintegeroptionalSets the maximum number of resources returned in this page. Applies to Aggregate token usage across authorized Projects.
offsetintegeroptionalSkips ordered breakdown rows. Summary and included Project IDs cover the whole authorized query, independent of pagination.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — summary: object (required); rows: array<object> (required); nextOffset: integer | null (required); coverage: object (required); projectIds: array<string> (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)