Costs

admin.organization.usage.costs() -> UsageCostsResponse

GET/organization/costs

Get costs details for the organization.

ParametersExpand Collapse

start_time: int

Start time (Unix seconds) of the query time range, inclusive.

api_key_ids: Optional[Sequence[str]]

Return only costs for these API keys.

bucket_width: Optional[Literal["1d"]]

Width of each time bucket in response. Currently only 1d is supported, default to 1d.

end_time: Optional[int]

End time (Unix seconds) of the query time range, exclusive.

group_by: Optional[List[Literal["project_id", "line_item", "api_key_id"]]]

Group the costs by the specified fields. Support fields include project_id, line_item, api_key_id and any combination of them.

One of the following:

"project_id"

"line_item"

"api_key_id"

limit: Optional[int]

A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7.

page: Optional[str]

A cursor for use in pagination. Corresponding to the next_page field from the previous response.

project_ids: Optional[Sequence[str]]

Return only costs for these projects.

ReturnsExpand Collapse

class UsageCostsResponse: …

data: List[Data]

end_time: int

object: Literal["bucket"]

results: List[DataResult]

One of the following:

class DataResultOrganizationUsageCompletionsResult: …

The aggregated completions usage details of the specific time bucket.

input_tokens: int

The aggregated number of text input tokens used, including cached tokens. For customers subscribe to scale tier, this includes scale tier tokens.

num_model_requests: int

The count of requests made to the model.

object: Literal["organization.usage.completions.result"]

output_tokens: int

The aggregated number of text output tokens used. For customers subscribe to scale tier, this includes scale tier tokens.

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API key ID of the grouped usage result.

batch: Optional[bool]

When group_by=batch, this field tells whether the grouped usage result is batch or not.

input_audio_tokens: Optional[int]

The aggregated number of audio input tokens used, including cached tokens.

input_cached_tokens: Optional[int]

The aggregated number of text input tokens that has been cached from previous requests. For customers subscribe to scale tier, this includes scale tier tokens.

model: Optional[str]

When group_by=model, this field provides the model name of the grouped usage result.

output_audio_tokens: Optional[int]

The aggregated number of audio output tokens used.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

service_tier: Optional[str]

When group_by=service_tier, this field provides the service tier of the grouped usage result.

user_id: Optional[str]

When group_by=user_id, this field provides the user ID of the grouped usage result.

class DataResultOrganizationUsageEmbeddingsResult: …

The aggregated embeddings usage details of the specific time bucket.

input_tokens: int

The aggregated number of input tokens used.

num_model_requests: int

The count of requests made to the model.

object: Literal["organization.usage.embeddings.result"]

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API key ID of the grouped usage result.

model: Optional[str]

When group_by=model, this field provides the model name of the grouped usage result.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

user_id: Optional[str]

When group_by=user_id, this field provides the user ID of the grouped usage result.

class DataResultOrganizationUsageModerationsResult: …

The aggregated moderations usage details of the specific time bucket.

input_tokens: int

The aggregated number of input tokens used.

num_model_requests: int

The count of requests made to the model.

object: Literal["organization.usage.moderations.result"]

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API key ID of the grouped usage result.

model: Optional[str]

When group_by=model, this field provides the model name of the grouped usage result.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

user_id: Optional[str]

When group_by=user_id, this field provides the user ID of the grouped usage result.

class DataResultOrganizationUsageImagesResult: …

The aggregated images usage details of the specific time bucket.

images: int

The number of images processed.

num_model_requests: int

The count of requests made to the model.

object: Literal["organization.usage.images.result"]

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API key ID of the grouped usage result.

model: Optional[str]

When group_by=model, this field provides the model name of the grouped usage result.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

size: Optional[str]

When group_by=size, this field provides the image size of the grouped usage result.

source: Optional[str]

When group_by=source, this field provides the source of the grouped usage result, possible values are image.generation, image.edit, image.variation.

user_id: Optional[str]

When group_by=user_id, this field provides the user ID of the grouped usage result.

class DataResultOrganizationUsageAudioSpeechesResult: …

The aggregated audio speeches usage details of the specific time bucket.

characters: int

The number of characters processed.

num_model_requests: int

The count of requests made to the model.

object: Literal["organization.usage.audio_speeches.result"]

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API key ID of the grouped usage result.

model: Optional[str]

When group_by=model, this field provides the model name of the grouped usage result.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

user_id: Optional[str]

When group_by=user_id, this field provides the user ID of the grouped usage result.

class DataResultOrganizationUsageAudioTranscriptionsResult: …

The aggregated audio transcriptions usage details of the specific time bucket.

num_model_requests: int

The count of requests made to the model.

object: Literal["organization.usage.audio_transcriptions.result"]

seconds: int

The number of seconds processed.

formatint64

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API key ID of the grouped usage result.

model: Optional[str]

When group_by=model, this field provides the model name of the grouped usage result.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

user_id: Optional[str]

When group_by=user_id, this field provides the user ID of the grouped usage result.

class DataResultOrganizationUsageVectorStoresResult: …

The aggregated vector stores usage details of the specific time bucket.

object: Literal["organization.usage.vector_stores.result"]

usage_bytes: int

The vector stores usage in bytes.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

class DataResultOrganizationUsageCodeInterpreterSessionsResult: …

The aggregated code interpreter sessions usage details of the specific time bucket.

num_sessions: int

The number of code interpreter sessions.

object: Literal["organization.usage.code_interpreter_sessions.result"]

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped usage result.

class DataResultOrganizationCostsResult: …

The aggregated costs details of the specific time bucket.

object: Literal["organization.costs.result"]

amount: Optional[DataResultOrganizationCostsResultAmount]

The monetary value in its associated currency.

currency: Optional[str]

Lowercase ISO-4217 currency e.g. “usd”

value: Optional[float]

The numeric value of the cost.

api_key_id: Optional[str]

When group_by=api_key_id, this field provides the API Key ID of the grouped costs result.

line_item: Optional[str]

When group_by=line_item, this field provides the line item of the grouped costs result.

project_id: Optional[str]

When group_by=project_id, this field provides the project ID of the grouped costs result.

start_time: int

has_more: bool

next_page: Optional[str]

object: Literal["page"]

Costs

import os
from openai import OpenAI

client = OpenAI(
    admin_api_key=os.environ.get("OPENAI_ADMIN_KEY"),  # This is the default and can be omitted
)
response = client.admin.organization.usage.costs(
    start_time=0,
)
print(response.data)

{
    "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,
                    "api_key_id": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Returns Examples

{
    "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,
                    "api_key_id": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}

Suggested

Costs

ParametersExpand Collapse

ReturnsExpand Collapse

Costs

Returns Examples