openai_get_usage
Retrieve OpenAI API usage metrics in time-bucketed intervals, with filters for category, project, user, API key, and model to analyze consumption trends.
Instructions
Query time-bucketed API usage for the organization.
`limit` caps the number of time buckets returned, with different
defaults/maximums per bucket_width: 1d -> default 7, max 31; 1h ->
default 24, max 168; 1m -> default 60, max 1440.
Args:
category: Which usage type to query — one of: completions,
embeddings, moderations, images, audio_speeches,
audio_transcriptions, vector_stores, code_interpreter_sessions,
file_search_calls, web_search_calls.
start_time: Start of the query range, inclusive (Unix seconds).
end_time: End of the query range, exclusive (Unix seconds).
bucket_width: Time bucket size — `1m`, `1h`, or `1d` (default `1d`).
group_by: Fields to group by, e.g. project_id, user_id, api_key_id,
model, batch, service_tier (supported fields vary by category).
project_ids: Only include usage for these projects.
user_ids: Only include usage for these users.
api_key_ids: Only include usage for these API keys.
models: Only include usage for these models.
limit: Number of time buckets to return.
page: Pagination cursor from a previous response's `next_page`.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| models | No | ||
| category | Yes | ||
| end_time | No | ||
| group_by | No | ||
| user_ids | No | ||
| start_time | Yes | ||
| api_key_ids | No | ||
| project_ids | No | ||
| bucket_width | No | 1d |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |