Sample - OpenAI API
GET/organization/usage/images

List organization image usage

Lists image usage for an organization across a Unix-time range and returns the results in time buckets. Use start_time and the optional end_time to define the range, then filter or group results by sources, sizes, projects, users, API keys, or models. Use page to retrieve the next page when the response indicates more results are available.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

12 parameters
start_timeintegerrequired
The inclusive start of the usage range as a Unix timestamp in seconds.
end_timeintegeroptional
The exclusive end of the usage range as a Unix timestamp in seconds.
bucket_widthstringoptional
The time-bucket width: `1m`, `1h`, or `1d`. Defaults to `1d` when omitted.
Allowed:1m1h1dDefault:1d
sourcesarray<string>optional
Filter usage by one or more sources: `image.generation`, `image.edit`, or `image.variation`.
sizesarray<string>optional
Filter usage by one or more image sizes: `256x256`, `512x512`, `1024x1024`, `1792x1792`, or `1024x1792`.
project_idsarray<string>optional
Filter usage to the specified project identifiers.
user_idsarray<string>optional
Filter usage to the specified user identifiers.
api_key_idsarray<string>optional
Filter usage to the specified API key identifiers.
modelsarray<string>optional
Filter usage to the specified model identifiers.
group_byarray<string>optional
Group results by one or more of `project_id`, `user_id`, `api_key_id`, `model`, `size`, or `source`.
limitintegeroptional
The number of time buckets to return. Defaults to 7 for `1d`, 24 for `1h`, or 60 for `1m`; maximums are 31, 168, and 1440 respectively.
pagestringoptional
A pagination cursor from the previous response's `next_page` field.

2 status codes
200Returns a usage page containing time-bucketed image usage data, a `has_more` indicator, and a `next_page` cursor when additional results are available.
objectstringrequired
Allowed:page
dataarray<object>required
has_morebooleanrequired
next_pagestringrequired
429Returned when the request is rejected because the rate limit has been exceeded.
errorobjectrequired

Error handling

start_time is required and must be a Unix timestamp in seconds; end_time, when supplied, defines the exclusive end of the range. bucket_width must be 1m, 1h, or 1d, and sources, sizes, and group_by must use only their documented values. A 429 is returned when the request exceeds the rate limit.