Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Costs

client.admin.organization.usage.costs(query, options?): UsageCostsResponse { data, has_more, next_page, object }
GET
/organization/costs

Get costs details for the organization.

Costs

import OpenAI from 'openai';

const client = new OpenAI({
  adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted
});

const response = await client.admin.organization.usage.costs({ start_time: 0 });

console.log(response.data);
Response example
{
    "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,
                    "quantity": null,
                    "quantity_unit": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}
Parameters
query: UsageCostsParams { start_time, api_key_ids, bucket_width, 6 more }
start_time: number

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

api_key_ids?: Array<string>

Return only costs for these API keys.

bucket_width?: "1d"

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

end_time?: number

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

group_by?: Array<"project_id" | "user_id" | "line_item" | 2 more>

Group the costs by the specified fields. Supported fields include project_id, user_id, line_item, api_key_id, and api_source. Support for combining user_id with project_id grouping or the project_ids filter depends on the organization and requested time range. Unsupported combinations return HTTP 400. When grouped by api_source, results use agents_api for attributed Agents API activity and unlabeled for all other activity. Without source grouping, api_source is null.

limit?: number

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

line_items?: Array<string>

Return only costs for these exact line item names. Each value must match the complete line_item value, for example gpt-6-astra, input_tokens.

page?: string

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

project_ids?: Array<string>

Return only costs for these projects.

Returns
UsageCostsResponse { data, has_more, next_page, object }
data: Array<Data>
has_more: boolean
next_page: string | null
object: "page"
Returns Examples
Response example
{
    "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,
                    "quantity": null,
                    "quantity_unit": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}