---
title: "Get completions usage details for the organization."
url: "https://kongair.terwilligar.com/apis/openai-api-2-3-0/versions/ea92d048-c746-4ead-a6a8-da28d93137d1/operations/usage-completions"
---

> Full API specification: https://kongair.terwilligar.com/apis/openai-api-2-3-0/versions/ea92d048-c746-4ead-a6a8-da28d93137d1.md

# Get completions usage details for the organization.

`GET` `/organization/usage/completions`

Operation ID: `usage-completions`

## Query parameters

- `start_time` (integer, required) - Start time (Unix seconds) of the query time range, inclusive.
- `end_time` (integer, optional) - End time (Unix seconds) of the query time range, exclusive.
- `bucket_width` (string, optional) - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.
- `project_ids` (array, optional) - Return only usage for these projects.
- `user_ids` (array, optional) - Return only usage for these users.
- `api_key_ids` (array, optional) - Return only usage for these API keys.
- `models` (array, optional) - Return only usage for these models.
- `batch` (boolean, optional) - If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both.
- `group_by` (array, optional) - 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.
- `limit` (integer, optional) - 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
- `page` (string, optional) - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.

## Responses

- `200` - Usage data retrieved successfully.

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: OpenAI API
  version: 2.3.0
servers:
  - url: https://api.openai.com/v1
paths:
  /organization/usage/completions:
    get:
      summary: Get completions usage details for the organization.
      operationId: usage-completions
      tags:
        - Usage
      parameters:
        - name: start_time
          in: query
          description: Start time (Unix seconds) of the query time range, inclusive.
          required: true
          schema:
            type: integer
        - name: end_time
          in: query
          description: End time (Unix seconds) of the query time range, exclusive.
          required: false
          schema:
            type: integer
        - name: bucket_width
          in: query
          description: Width of each time bucket in response. Currently `1m`, `1h` and
            `1d` are supported, default to `1d`.
          required: false
          schema:
            type: string
            enum:
              - 1m
              - 1h
              - 1d
            default: 1d
        - name: project_ids
          in: query
          description: Return only usage for these projects.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: user_ids
          in: query
          description: Return only usage for these users.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: api_key_ids
          in: query
          description: Return only usage for these API keys.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: models
          in: query
          description: Return only usage for these models.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: batch
          in: query
          description: >
            If `true`, return batch jobs only. If `false`, return non-batch jobs
            only. By default, return both.
          required: false
          schema:
            type: boolean
        - name: group_by
          in: query
          description: 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.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - project_id
                - user_id
                - api_key_id
                - model
                - batch
        - name: limit
          in: query
          description: |
            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
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: A cursor for use in pagination. Corresponding to the `next_page`
            field from the previous response.
          schema:
            type: string
      responses:
        "200":
          description: Usage data retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageResponse"
      x-oaiMeta:
        name: Completions
        group: usage-completions
        returns: A list of paginated, time bucketed [Completions
          usage](/docs/api-reference/usage/completions_object) objects.
        examples:
          request:
            curl: |
              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"
          response: >
            {
                "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,
                                "input_audio_tokens": 0,
                                "output_audio_tokens": 0,
                                "num_model_requests": 5,
                                "project_id": null,
                                "user_id": null,
                                "api_key_id": null,
                                "model": null,
                                "batch": null
                            }
                        ]
                    }
                ],
                "has_more": true,
                "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA="
            }
security:
  - ApiKeyAuth: []
components:
  schemas:
    UsageResponse:
      type: object
      properties:
        object:
          type: string
          enum:
            - page
          x-stainless-const: true
        data:
          type: array
          items:
            $ref: "#/components/schemas/UsageTimeBucket"
        has_more:
          type: boolean
        next_page:
          type: string
      required:
        - object
        - data
        - has_more
        - next_page
    UsageTimeBucket:
      type: object
      properties:
        object:
          type: string
          enum:
            - bucket
          x-stainless-const: true
        start_time:
          type: integer
        end_time:
          type: integer
        result:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/UsageCompletionsResult"
              - $ref: "#/components/schemas/UsageEmbeddingsResult"
              - $ref: "#/components/schemas/UsageModerationsResult"
              - $ref: "#/components/schemas/UsageImagesResult"
              - $ref: "#/components/schemas/UsageAudioSpeechesResult"
              - $ref: "#/components/schemas/UsageAudioTranscriptionsResult"
              - $ref: "#/components/schemas/UsageVectorStoresResult"
              - $ref: "#/components/schemas/UsageCodeInterpreterSessionsResult"
              - $ref: "#/components/schemas/CostsResult"
      required:
        - object
        - start_time
        - end_time
        - result
    UsageCompletionsResult:
      type: object
      description: The aggregated completions usage details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.completions.result
          x-stainless-const: true
        input_tokens:
          type: integer
          description: The aggregated number of text input tokens used, including cached
            tokens. For customers subscribe to scale tier, this includes scale
            tier tokens.
        input_cached_tokens:
          type: integer
          description: 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.
        output_tokens:
          type: integer
          description: The aggregated number of text output tokens used. For customers
            subscribe to scale tier, this includes scale tier tokens.
        input_audio_tokens:
          type: integer
          description: The aggregated number of audio input tokens used, including cached
            tokens.
        output_audio_tokens:
          type: integer
          description: The aggregated number of audio output tokens used.
        num_model_requests:
          type: integer
          description: The count of requests made to the model.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
        user_id:
          type: string
          nullable: true
          description: When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
        api_key_id:
          type: string
          nullable: true
          description: When `group_by=api_key_id`, this field provides the API key ID of
            the grouped usage result.
        model:
          type: string
          nullable: true
          description: When `group_by=model`, this field provides the model name of the
            grouped usage result.
        batch:
          type: boolean
          nullable: true
          description: When `group_by=batch`, this field tells whether the grouped usage
            result is batch or not.
      required:
        - object
        - input_tokens
        - output_tokens
        - num_model_requests
      x-oaiMeta:
        name: Completions usage object
        example: |
          {
              "object": "organization.usage.completions.result",
              "input_tokens": 5000,
              "output_tokens": 1000,
              "input_cached_tokens": 4000,
              "input_audio_tokens": 300,
              "output_audio_tokens": 200,
              "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
          }
    UsageEmbeddingsResult:
      type: object
      description: The aggregated embeddings usage details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.embeddings.result
          x-stainless-const: true
        input_tokens:
          type: integer
          description: The aggregated number of input tokens used.
        num_model_requests:
          type: integer
          description: The count of requests made to the model.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
        user_id:
          type: string
          nullable: true
          description: When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
        api_key_id:
          type: string
          nullable: true
          description: When `group_by=api_key_id`, this field provides the API key ID of
            the grouped usage result.
        model:
          type: string
          nullable: true
          description: When `group_by=model`, this field provides the model name of the
            grouped usage result.
      required:
        - object
        - input_tokens
        - num_model_requests
      x-oaiMeta:
        name: Embeddings usage object
        example: |
          {
              "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"
          }
    UsageModerationsResult:
      type: object
      description: The aggregated moderations usage details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.moderations.result
          x-stainless-const: true
        input_tokens:
          type: integer
          description: The aggregated number of input tokens used.
        num_model_requests:
          type: integer
          description: The count of requests made to the model.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
        user_id:
          type: string
          nullable: true
          description: When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
        api_key_id:
          type: string
          nullable: true
          description: When `group_by=api_key_id`, this field provides the API key ID of
            the grouped usage result.
        model:
          type: string
          nullable: true
          description: When `group_by=model`, this field provides the model name of the
            grouped usage result.
      required:
        - object
        - input_tokens
        - num_model_requests
      x-oaiMeta:
        name: Moderations usage object
        example: |
          {
              "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"
          }
    UsageImagesResult:
      type: object
      description: The aggregated images usage details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.images.result
          x-stainless-const: true
        images:
          type: integer
          description: The number of images processed.
        num_model_requests:
          type: integer
          description: The count of requests made to the model.
        source:
          type: string
          nullable: true
          description: When `group_by=source`, this field provides the source of the
            grouped usage result, possible values are `image.generation`,
            `image.edit`, `image.variation`.
        size:
          type: string
          nullable: true
          description: When `group_by=size`, this field provides the image size of the
            grouped usage result.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
        user_id:
          type: string
          nullable: true
          description: When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
        api_key_id:
          type: string
          nullable: true
          description: When `group_by=api_key_id`, this field provides the API key ID of
            the grouped usage result.
        model:
          type: string
          nullable: true
          description: When `group_by=model`, this field provides the model name of the
            grouped usage result.
      required:
        - object
        - images
        - num_model_requests
      x-oaiMeta:
        name: Images usage object
        example: |
          {
              "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"
          }
    UsageAudioSpeechesResult:
      type: object
      description: The aggregated audio speeches usage details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.audio_speeches.result
          x-stainless-const: true
        characters:
          type: integer
          description: The number of characters processed.
        num_model_requests:
          type: integer
          description: The count of requests made to the model.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
        user_id:
          type: string
          nullable: true
          description: When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
        api_key_id:
          type: string
          nullable: true
          description: When `group_by=api_key_id`, this field provides the API key ID of
            the grouped usage result.
        model:
          type: string
          nullable: true
          description: When `group_by=model`, this field provides the model name of the
            grouped usage result.
      required:
        - object
        - characters
        - num_model_requests
      x-oaiMeta:
        name: Audio speeches usage object
        example: |
          {
              "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"
          }
    UsageAudioTranscriptionsResult:
      type: object
      description: The aggregated audio transcriptions usage details of the specific
        time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.audio_transcriptions.result
          x-stainless-const: true
        seconds:
          type: integer
          description: The number of seconds processed.
        num_model_requests:
          type: integer
          description: The count of requests made to the model.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
        user_id:
          type: string
          nullable: true
          description: When `group_by=user_id`, this field provides the user ID of the
            grouped usage result.
        api_key_id:
          type: string
          nullable: true
          description: When `group_by=api_key_id`, this field provides the API key ID of
            the grouped usage result.
        model:
          type: string
          nullable: true
          description: When `group_by=model`, this field provides the model name of the
            grouped usage result.
      required:
        - object
        - seconds
        - num_model_requests
      x-oaiMeta:
        name: Audio transcriptions usage object
        example: |
          {
              "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"
          }
    UsageVectorStoresResult:
      type: object
      description: The aggregated vector stores usage details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.vector_stores.result
          x-stainless-const: true
        usage_bytes:
          type: integer
          description: The vector stores usage in bytes.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
      required:
        - object
        - usage_bytes
      x-oaiMeta:
        name: Vector stores usage object
        example: |
          {
              "object": "organization.usage.vector_stores.result",
              "usage_bytes": 1024,
              "project_id": "proj_abc"
          }
    UsageCodeInterpreterSessionsResult:
      type: object
      description: The aggregated code interpreter sessions usage details of the
        specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.usage.code_interpreter_sessions.result
          x-stainless-const: true
        num_sessions:
          type: integer
          description: The number of code interpreter sessions.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped usage result.
      required:
        - object
        - sessions
      x-oaiMeta:
        name: Code interpreter sessions usage object
        example: |
          {
              "object": "organization.usage.code_interpreter_sessions.result",
              "num_sessions": 1,
              "project_id": "proj_abc"
          }
    CostsResult:
      type: object
      description: The aggregated costs details of the specific time bucket.
      properties:
        object:
          type: string
          enum:
            - organization.costs.result
          x-stainless-const: true
        amount:
          type: object
          description: The monetary value in its associated currency.
          properties:
            value:
              type: number
              description: The numeric value of the cost.
            currency:
              type: string
              description: Lowercase ISO-4217 currency e.g. "usd"
        line_item:
          type: string
          nullable: true
          description: When `group_by=line_item`, this field provides the line item of the
            grouped costs result.
        project_id:
          type: string
          nullable: true
          description: When `group_by=project_id`, this field provides the project ID of
            the grouped costs result.
      required:
        - object
      x-oaiMeta:
        name: Costs object
        example: |
          {
              "object": "organization.costs.result",
              "amount": {
                "value": 0.06,
                "currency": "usd"
              },
              "line_item": "Image models",
              "project_id": "proj_abc"
          }
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
```