## Completions

`client.admin.organization.usage.completions(UsageCompletionsParamsquery, RequestOptionsoptions?): UsageCompletionsResponse`

**get** `/organization/usage/completions`

Get completions usage details for the organization.

### Parameters

- `query: UsageCompletionsParams`

  - `start_time: number`

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

  - `api_key_ids?: Array<string>`

    Return only usage for these API keys.

  - `batch?: boolean`

    If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both.

  - `bucket_width?: "1m" | "1h" | "1d"`

    Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.

    - `"1m"`

    - `"1h"`

    - `"1d"`

  - `end_time?: number`

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

  - `group_by?: Array<"project_id" | "user_id" | "api_key_id" | 4 more>`

    Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch`, `service_tier`, `api_source` or any combination of them. 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.

    - `"project_id"`

    - `"user_id"`

    - `"api_key_id"`

    - `"model"`

    - `"batch"`

    - `"service_tier"`

    - `"api_source"`

  - `limit?: number`

    Specifies the number of buckets to return.

    - `bucket_width=1d`: default: 7, max: 31
    - `bucket_width=1h`: default: 24, max: 168
    - `bucket_width=1m`: default: 60, max: 1440

  - `models?: Array<string>`

    Return only usage for these models.

  - `page?: string`

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

  - `project_ids?: Array<string>`

    Return only usage for these projects.

  - `user_ids?: Array<string>`

    Return only usage for these users.

### Returns

- `UsageCompletionsResponse`

  - `data: Array<Data>`

    - `end_time: number`

    - `object: "bucket"`

      - `"bucket"`

    - `results: Array<OrganizationUsageCompletionsResult | OrganizationUsageEmbeddingsResult | OrganizationUsageModerationsResult | 8 more>`

      - `OrganizationUsageCompletionsResult`

        The aggregated completions usage details of the specific time bucket.

        - `input_tokens: number`

          The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens.

        - `num_model_requests: number`

          The count of requests made to the model.

        - `object: "organization.usage.completions.result"`

          - `"organization.usage.completions.result"`

        - `output_tokens: number`

          The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens.

        - `api_key_id?: string | null`

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

        - `api_source?: "agents_api" | "unlabeled" | null`

          When grouped by `api_source`, `agents_api` identifies attributed Agents API activity and `unlabeled` includes all records without published source attribution, including historical and unknown origins. Unlabeled does not imply direct API usage. Without source grouping, this field is null.

          - `"agents_api"`

          - `"unlabeled"`

        - `batch?: boolean | null`

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

        - `input_audio_tokens?: number`

          The aggregated number of uncached audio input tokens used.

        - `input_cache_write_12h_tokens?: number`

          The aggregated number of input tokens written to the cache with a 12-hour retention period.

        - `input_cache_write_30m_tokens?: number | null`

          The aggregated number of input tokens written to the cache with a 30-minute retention period. May be absent or null for older responses.

        - `input_cache_write_tokens?: number`

          The aggregated number of input tokens written to the cache across 30-minute and 12-hour retention periods.

        - `input_cached_audio_tokens?: number`

          The aggregated number of cached audio input tokens used.

        - `input_cached_image_tokens?: number`

          The aggregated number of cached image input tokens used.

        - `input_cached_text_tokens?: number`

          The aggregated number of cached text input tokens used.

        - `input_cached_tokens?: number`

          The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens.

        - `input_image_tokens?: number`

          The aggregated number of uncached image input tokens used.

        - `input_text_tokens?: number`

          The aggregated number of uncached text input tokens used, excluding cache-write tokens.

        - `input_uncached_tokens?: number`

          The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens.

        - `model?: string | null`

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

        - `output_audio_tokens?: number`

          The aggregated number of audio output tokens used.

        - `output_image_tokens?: number`

          The aggregated number of image output tokens used.

        - `output_text_tokens?: number`

          The aggregated number of text output tokens used.

        - `project_id?: string | null`

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

        - `service_tier?: string | null`

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

        - `user_id?: string | null`

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

      - `OrganizationUsageEmbeddingsResult`

        The aggregated embeddings usage details of the specific time bucket.

        - `input_tokens: number`

          The aggregated number of input tokens used.

        - `num_model_requests: number`

          The count of requests made to the model.

        - `object: "organization.usage.embeddings.result"`

          - `"organization.usage.embeddings.result"`

        - `api_key_id?: string | null`

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

        - `model?: string | null`

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

        - `project_id?: string | null`

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

        - `user_id?: string | null`

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

      - `OrganizationUsageModerationsResult`

        The aggregated moderations usage details of the specific time bucket.

        - `input_tokens: number`

          The aggregated number of input tokens used.

        - `num_model_requests: number`

          The count of requests made to the model.

        - `object: "organization.usage.moderations.result"`

          - `"organization.usage.moderations.result"`

        - `api_key_id?: string | null`

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

        - `model?: string | null`

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

        - `project_id?: string | null`

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

        - `user_id?: string | null`

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

      - `OrganizationUsageImagesResult`

        The aggregated images usage details of the specific time bucket.

        - `images: number`

          The number of images processed.

        - `num_model_requests: number`

          The count of requests made to the model.

        - `object: "organization.usage.images.result"`

          - `"organization.usage.images.result"`

        - `api_key_id?: string | null`

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

        - `model?: string | null`

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

        - `project_id?: string | null`

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

        - `size?: string | null`

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

        - `source?: string | null`

          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?: string | null`

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

      - `OrganizationUsageAudioSpeechesResult`

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

        - `characters: number`

          The number of characters processed.

        - `num_model_requests: number`

          The count of requests made to the model.

        - `object: "organization.usage.audio_speeches.result"`

          - `"organization.usage.audio_speeches.result"`

        - `api_key_id?: string | null`

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

        - `model?: string | null`

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

        - `project_id?: string | null`

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

        - `user_id?: string | null`

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

      - `OrganizationUsageAudioTranscriptionsResult`

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

        - `num_model_requests: number`

          The count of requests made to the model.

        - `object: "organization.usage.audio_transcriptions.result"`

          - `"organization.usage.audio_transcriptions.result"`

        - `seconds: number`

          The number of seconds processed.

          `format: int64`

        - `api_key_id?: string | null`

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

        - `model?: string | null`

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

        - `project_id?: string | null`

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

        - `user_id?: string | null`

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

      - `OrganizationUsageVectorStoresResult`

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

        - `object: "organization.usage.vector_stores.result"`

          - `"organization.usage.vector_stores.result"`

        - `usage_bytes: number`

          The vector stores usage in bytes.

        - `project_id?: string | null`

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

      - `OrganizationUsageCodeInterpreterSessionsResult`

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

        - `num_sessions: number`

          The number of code interpreter sessions.

        - `object: "organization.usage.code_interpreter_sessions.result"`

          - `"organization.usage.code_interpreter_sessions.result"`

        - `project_id?: string | null`

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

      - `OrganizationUsageFileSearchesResult`

        The aggregated file search calls usage details of the specific time bucket.

        - `num_requests: number`

          The count of file search calls.

        - `object: "organization.usage.file_searches.result"`

          - `"organization.usage.file_searches.result"`

        - `api_key_id?: string | null`

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

        - `project_id?: string | null`

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

        - `user_id?: string | null`

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

        - `vector_store_id?: string | null`

          When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result.

      - `OrganizationUsageWebSearchesResult`

        The aggregated web search calls usage details of the specific time bucket.

        - `num_model_requests: number`

          The count of model requests.

        - `num_requests: number`

          The count of web search calls.

        - `object: "organization.usage.web_searches.result"`

          - `"organization.usage.web_searches.result"`

        - `api_key_id?: string | null`

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

        - `api_source?: "agents_api" | "unlabeled" | null`

          When grouped by `api_source`, `agents_api` identifies attributed Agents API activity and `unlabeled` includes all records without published source attribution, including historical and unknown origins. Unlabeled does not imply direct API usage. Without source grouping, this field is null.

          - `"agents_api"`

          - `"unlabeled"`

        - `context_level?: string | null`

          When `group_by=context_level`, this field provides the search context size of the grouped usage result.

        - `model?: string | null`

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

        - `project_id?: string | null`

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

        - `user_id?: string | null`

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

      - `OrganizationCostsResult`

        The aggregated costs details of the specific time bucket.

        - `object: "organization.costs.result"`

          - `"organization.costs.result"`

        - `amount?: Amount`

          The monetary value in its associated currency.

          - `currency?: string`

            Lowercase ISO-4217 currency e.g. "usd"

          - `value?: number`

            The numeric value of the cost.

        - `api_key_id?: string | null`

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

        - `api_source?: "agents_api" | "unlabeled" | null`

          When grouped by `api_source`, `agents_api` identifies attributed Agents API activity and `unlabeled` includes all records without published source attribution, including historical and unknown origins. Unlabeled does not imply direct API usage. Without source grouping, this field is null.

          - `"agents_api"`

          - `"unlabeled"`

        - `line_item?: string | null`

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

        - `project_id?: string | null`

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

        - `quantity?: number | null`

          When `group_by=line_item`, this field provides the quantity of the grouped costs result.

        - `quantity_unit?: CostQuantityUnit | null`

          The unit of the `quantity` value. If no single supported unit applies to the result, this field is `null`.

          - `(string & {})`

          - `"tokens" | "1000_tokens" | "duration_seconds" | 5 more`

            - `"tokens"`

            - `"1000_tokens"`

            - `"duration_seconds"`

            - `"duration_minutes"`

            - `"duration_hours"`

            - `"gibibyte_hours"`

            - `"images"`

            - `"characters"`

        - `user_id?: string | null`

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

    - `start_time: number`

  - `has_more: boolean`

  - `next_page: string | null`

  - `object: "page"`

    - `"page"`

### Example

```typescript
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.completions({ start_time: 0 });

console.log(response.data);
```

#### 200 — Example

```json
{
  "data": [
    {
      "end_time": 0,
      "object": "bucket",
      "results": [
        {
          "input_tokens": 0,
          "num_model_requests": 0,
          "object": "organization.usage.completions.result",
          "output_tokens": 0,
          "api_key_id": "api_key_id",
          "api_source": "agents_api",
          "batch": true,
          "input_audio_tokens": 0,
          "input_cache_write_12h_tokens": 0,
          "input_cache_write_30m_tokens": 0,
          "input_cache_write_tokens": 0,
          "input_cached_audio_tokens": 0,
          "input_cached_image_tokens": 0,
          "input_cached_text_tokens": 0,
          "input_cached_tokens": 0,
          "input_image_tokens": 0,
          "input_text_tokens": 0,
          "input_uncached_tokens": 0,
          "model": "model",
          "output_audio_tokens": 0,
          "output_image_tokens": 0,
          "output_text_tokens": 0,
          "project_id": "project_id",
          "service_tier": "service_tier",
          "user_id": "user_id"
        }
      ],
      "start_time": 0
    }
  ],
  "has_more": true,
  "next_page": "next_page",
  "object": "page"
}
```
