Get Usage Summary

GET /environments/{env_id}/usage_summary

Get Usage Summary

Roll the environment's usage up into one bucket per day, model or caller API key over the given window.

Counts are request-level: request_count is the number of distinct requests in the bucket, not the number of upstream attempts, so a request that retried or failed over counts once. Token and cost figures are sums over the attempt rows, which comes to the same thing because a failed attempt carries no tokens and no cost.

A request whose attempts straddle a bucket boundary is counted in both buckets, so summing buckets over-counts the window total — read usage_metrics when you need a figure for the whole window.

Parameters

• env_id (path, string, required): Environment ID.

• from (query, string, required): Inclusive lower bound on occurred_at, RFC 3339.

• to (query, string, required): Exclusive upper bound on occurred_at, RFC 3339. Must be strictly after from.

• group_by (query, string, required): Bucket key. day yields a UTC YYYY-MM-DD key; model yields the model alias the caller addressed (the Model-Group name for routed requests, a model id for rows from gateways predating alias capture); api_key yields a caller API key id. An empty key means the attribute was absent on the row.

Responses

• 200: OK

• data (array, required):

• data[].key (string, required): Bucket key, in the shape group_by selected: a UTC YYYY-MM-DD date, a model alias, or a caller API key id. An empty string means the attribute was absent on those rows.

• data[].request_count (integer, required):

• data[].success_count (integer, required): Requests in the bucket with at least one 2xx attempt. A request that failed twice and then succeeded counts as one success here, not as two failures and a success.

• data[].prompt_tokens (integer, required):

• data[].completion_tokens (integer, required):

• data[].cached_prompt_tokens (integer, required):

• data[].reasoning_tokens (integer, required):

• data[].cache_creation_tokens (integer, required):

• data[].cache_read_tokens (integer, required):

• data[].cache_hit_saved_input_tokens (integer, required):

• data[].cache_hit_saved_output_tokens (integer, required):

• data[].cost_usd (number, required):

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /environments/{env_id}/usage_summary, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /environments/{env_id}/usage_summary, response 400 above.

• 503: The deployment is not configured to serve this data. Response fields (application/json): identical to GET /environments/{env_id}/usage_summary, response 400 above.

cURL

curl -X GET '$AISIX_CP/environments/{env_id}/usage_summary' -H 'Authorization: Bearer $AISIX_TOKEN'