Usage
The Usage API provides detailed insights into your activity across the OpenAI API. It also includes a separate Costs endpoint, which offers visibility into your spend, breaking down consumption by invoice line items and project IDs.
While the Usage API delivers granular usage data, it may not always reconcile perfectly with the Costs due to minor differences in how usage and spend are recorded. For financial purposes, we recommend using the Costs endpoint or the Costs tab in the Usage Dashboard, which will reconcile back to your billing invoice.
Completions
Get completions usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
If true, return batch jobs only. If false, return non-batch jobs only. By default, return both.
Group the usage data by the specified fields. Support fields include project_id, user_id, api_key_id, model, batch or any combination of them.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Completions usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.completions.result",
"input_tokens": 1000,
"output_tokens": 500,
"input_cached_tokens": 800,
"num_model_requests": 5,
"project_id": null,
"user_id": null,
"api_key_id": null,
"model": null,
"batch": null
}
]
}
],
"has_more": true,
"next_page": "AAAAAGdGxdEiJdKOAAAAAGcqsYA="
}Completions usage object
The aggregated completions usage details of the specific time bucket.
The aggregated number of input tokens used. For customers subscribe to scale tier, this includes scale tier tokens.
The aggregated number of input tokens that has been cached from previous requests. For customers subscribe to scale tier, this includes scale tier tokens.
The aggregated number of output tokens used. For customers subscribe to scale tier, this includes scale tier tokens.
When group_by=project_id, this field provides the project ID of the grouped usage result.
When group_by=user_id, this field provides the user ID of the grouped usage result.
When group_by=api_key_id, this field provides the API key ID of the grouped usage result.
When group_by=model, this field provides the model name of the grouped usage result.
1
2
3
4
5
6
7
8
9
10
11
12
{
"object": "organization.usage.completions.result",
"input_tokens": 5000,
"output_tokens": 1000,
"input_cached_tokens": 4000,
"num_model_requests": 5,
"project_id": "proj_abc",
"user_id": "user-abc",
"api_key_id": "key_abc",
"model": "gpt-4o-mini-2024-07-18",
"batch": false
}Embeddings
Get embeddings usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Group the usage data by the specified fields. Support fields include project_id, user_id, api_key_id, model or any combination of them.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Embeddings usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.embeddings.result",
"input_tokens": 16,
"num_model_requests": 2,
"project_id": null,
"user_id": null,
"api_key_id": null,
"model": null
}
]
}
],
"has_more": false,
"next_page": null
}Embeddings usage object
The aggregated embeddings usage details of the specific time bucket.
When group_by=project_id, this field provides the project ID of the grouped usage result.
When group_by=user_id, this field provides the user ID of the grouped usage result.
When group_by=api_key_id, this field provides the API key ID of the grouped usage result.
1
2
3
4
5
6
7
8
9
{
"object": "organization.usage.embeddings.result",
"input_tokens": 20,
"num_model_requests": 2,
"project_id": "proj_abc",
"user_id": "user-abc",
"api_key_id": "key_abc",
"model": "text-embedding-ada-002-v2"
}Moderations
Get moderations usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Group the usage data by the specified fields. Support fields include project_id, user_id, api_key_id, model or any combination of them.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Moderations usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.moderations.result",
"input_tokens": 16,
"num_model_requests": 2,
"project_id": null,
"user_id": null,
"api_key_id": null,
"model": null
}
]
}
],
"has_more": false,
"next_page": null
}Moderations usage object
The aggregated moderations usage details of the specific time bucket.
When group_by=project_id, this field provides the project ID of the grouped usage result.
When group_by=user_id, this field provides the user ID of the grouped usage result.
When group_by=api_key_id, this field provides the API key ID of the grouped usage result.
1
2
3
4
5
6
7
8
9
{
"object": "organization.usage.moderations.result",
"input_tokens": 20,
"num_model_requests": 2,
"project_id": "proj_abc",
"user_id": "user-abc",
"api_key_id": "key_abc",
"model": "text-moderation"
}Images
Get images usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Return only usages for these sources. Possible values are image.generation, image.edit, image.variation or any combination of them.
Return only usages for these image sizes. Possible values are 256x256, 512x512, 1024x1024, 1792x1792, 1024x1792 or any combination of them.
Group the usage data by the specified fields. Support fields include project_id, user_id, api_key_id, model, size, source or any combination of them.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Images usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.images.result",
"images": 2,
"num_model_requests": 2,
"size": null,
"source": null,
"project_id": null,
"user_id": null,
"api_key_id": null,
"model": null
}
]
}
],
"has_more": false,
"next_page": null
}Images usage object
The aggregated images usage details of the specific time bucket.
When group_by=source, this field provides the source of the grouped usage result, possible values are image.generation, image.edit, image.variation.
When group_by=size, this field provides the image size of the grouped usage result.
When group_by=project_id, this field provides the project ID of the grouped usage result.
When group_by=user_id, this field provides the user ID of the grouped usage result.
When group_by=api_key_id, this field provides the API key ID of the grouped usage result.
1
2
3
4
5
6
7
8
9
10
11
{
"object": "organization.usage.images.result",
"images": 2,
"num_model_requests": 2,
"size": "1024x1024",
"source": "image.generation",
"project_id": "proj_abc",
"user_id": "user-abc",
"api_key_id": "key_abc",
"model": "dall-e-3"
}Audio speeches
Get audio speeches usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Group the usage data by the specified fields. Support fields include project_id, user_id, api_key_id, model or any combination of them.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Audio speeches usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.audio_speeches.result",
"characters": 45,
"num_model_requests": 1,
"project_id": null,
"user_id": null,
"api_key_id": null,
"model": null
}
]
}
],
"has_more": false,
"next_page": null
}Audio speeches usage object
The aggregated audio speeches usage details of the specific time bucket.
When group_by=project_id, this field provides the project ID of the grouped usage result.
When group_by=user_id, this field provides the user ID of the grouped usage result.
When group_by=api_key_id, this field provides the API key ID of the grouped usage result.
1
2
3
4
5
6
7
8
9
{
"object": "organization.usage.audio_speeches.result",
"characters": 45,
"num_model_requests": 1,
"project_id": "proj_abc",
"user_id": "user-abc",
"api_key_id": "key_abc",
"model": "tts-1"
}Audio transcriptions
Get audio transcriptions usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Group the usage data by the specified fields. Support fields include project_id, user_id, api_key_id, model or any combination of them.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Audio transcriptions usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.audio_transcriptions.result",
"seconds": 20,
"num_model_requests": 1,
"project_id": null,
"user_id": null,
"api_key_id": null,
"model": null
}
]
}
],
"has_more": false,
"next_page": null
}Audio transcriptions usage object
The aggregated audio transcriptions usage details of the specific time bucket.
When group_by=project_id, this field provides the project ID of the grouped usage result.
When group_by=user_id, this field provides the user ID of the grouped usage result.
When group_by=api_key_id, this field provides the API key ID of the grouped usage result.
1
2
3
4
5
6
7
8
9
{
"object": "organization.usage.audio_transcriptions.result",
"seconds": 10,
"num_model_requests": 1,
"project_id": "proj_abc",
"user_id": "user-abc",
"api_key_id": "key_abc",
"model": "tts-1"
}Vector stores
Get vector stores usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Group the usage data by the specified fields. Support fields include project_id.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Vector stores usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.vector_stores.result",
"usage_bytes": 1024,
"project_id": null
}
]
}
],
"has_more": false,
"next_page": null
}Vector stores usage object
The aggregated vector stores usage details of the specific time bucket.
1
2
3
4
5
{
"object": "organization.usage.vector_stores.result",
"usage_bytes": 1024,
"project_id": "proj_abc"
}Code interpreter sessions
Get code interpreter sessions usage details for the organization.
Query parameters
Width of each time bucket in response. Currently 1m, 1h and 1d are supported, default to 1d.
Group the usage data by the specified fields. Support fields include project_id.
Specifies the number of buckets to return.
bucket_width=1d: default: 7, max: 31bucket_width=1h: default: 24, max: 168bucket_width=1m: default: 60, max: 1440
Returns
A list of paginated, time bucketed Code interpreter sessions usage objects.
1
2
3
curl "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.usage.code_interpreter_sessions.result",
"sessions": 1,
"project_id": null
}
]
}
],
"has_more": false,
"next_page": null
}Code interpreter sessions usage object
The aggregated code interpreter sessions usage details of the specific time bucket.
1
2
3
4
5
{
"object": "organization.usage.code_interpreter_sessions.result",
"sessions": 1,
"project_id": "proj_abc"
}Costs
Get costs details for the organization.
Query parameters
Width of each time bucket in response. Currently only 1d is supported, default to 1d.
Group the costs by the specified fields. Support fields include project_id, line_item and any combination of them.
A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7.
Returns
A list of paginated, time bucketed Costs objects.
1
2
3
curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json"1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"object": "page",
"data": [
{
"object": "bucket",
"start_time": 1730419200,
"end_time": 1730505600,
"results": [
{
"object": "organization.costs.result",
"amount": {
"value": 0.06,
"currency": "usd"
},
"line_item": null,
"project_id": null
}
]
}
],
"has_more": false,
"next_page": null
}Costs object
The aggregated costs details of the specific time bucket.
1
2
3
4
5
6
7
8
9
{
"object": "organization.costs.result",
"amount": {
"value": 0.06,
"currency": "usd"
},
"line_item": "Image models",
"project_id": "proj_abc"
}