---
title: "Decisions"
method: GET
path: "/organization/usage/decisions"
---

# Decisions

`GET /organization/usage/decisions`

## Request

- Base URL: `https://api.openai.com/v1`
- URL: `https://api.openai.com/v1/organization/usage/decisions`
- Auth: HTTP bearer

Get Decisions API usage details for the organization.

## Query parameters

- `start_time` integer, required
- `end_time` integer, nullable
- `bucket_width` '1m' | '1h' | '1d'
- `limit` integer, nullable
- `page` string, nullable: A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.
- `project_ids` string[], nullable
- `group_by` DecisionsUsageGroupBy[], nullable
- `user_ids` string[], nullable
- `api_key_ids` string[], nullable
- `models` string[], nullable
- `batch` boolean, nullable

## Response `200`

Success

- PublicDecisionsUsageResponseResource
  - `object` 'page', required
  - `has_more` boolean, required
  - `next_page` string, nullable, required
  - `data` DecisionsUsageBucket[], required
    - `object` 'bucket', required
    - `start_time` integer, required
    - `end_time` integer, required
    - `results` DecisionsUsageResult[], required
      - `api_source` 'agents_api' | 'unlabeled'
      - `object` 'organization.usage.decisions.result', required
      - `input_tokens` integer, required: 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.
      - `input_cached_tokens` integer, nullable: 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_cache_write_tokens` integer, nullable: The aggregated number of input tokens written to the cache across 30-minute and 12-hour retention periods.
      - `input_cache_write_30m_tokens` integer, nullable: The aggregated number of input tokens written to the cache with a 30-minute retention period.
      - `input_cache_write_12h_tokens` integer, nullable: The aggregated number of input tokens written to the cache with a 12-hour retention period.
      - `input_uncached_tokens` integer, nullable: The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens.
      - `output_tokens` integer, required: The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens.
      - `input_text_tokens` integer, nullable: The aggregated number of uncached text input tokens used, excluding cache-write tokens.
      - `output_text_tokens` integer, nullable: The aggregated number of text output tokens used.
      - `input_cached_text_tokens` integer, nullable: The aggregated number of cached text input tokens used.
      - `input_audio_tokens` integer, nullable: The aggregated number of uncached audio input tokens used.
      - `input_cached_audio_tokens` integer, nullable: The aggregated number of cached audio input tokens used.
      - `output_audio_tokens` integer, nullable: The aggregated number of audio output tokens used.
      - `input_image_tokens` integer, nullable: The aggregated number of uncached image input tokens used.
      - `input_cached_image_tokens` integer, nullable: The aggregated number of cached image input tokens used.
      - `output_image_tokens` integer, nullable: The aggregated number of image output tokens used.
      - `num_model_requests` integer, required: The count of requests made to the model.
      - `project_id` string, nullable: When `group_by=project_id`, this field provides the project ID of the grouped usage result.
      - `user_id` string, nullable: When `group_by=user_id`, this field provides the user ID of the grouped usage result.
      - `api_key_id` string, nullable: When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result.
      - `model` string, nullable: When `group_by=model`, this field provides the model name of the grouped usage result.
      - `batch` boolean, nullable: When `group_by=batch`, this field tells whether the grouped usage result is batch or not.
      - `service_tier` string, nullable: When `group_by=service_tier`, this field provides the service tier of the grouped usage result.

## Other responses

- `400`: The request parameters are invalid or the requested operation cannot be performed.
- `403`: The caller does not have permission to perform this operation.
- `429`: The request was rejected because a rate limit was exceeded.

## Changes

- **2026-10-19** `0f7c2aa03117`: 1 info
  - added the optional property `data/items/results/items/input_cache_write_30m_tokens` to the response with the `200` status
- **2026-10-09** `8f037f570565`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openai/apis/openapi/changes/organization/usage/decisions/get.md)

---

[API](https://skmtc.dev/openai/apis/openapi.md) - [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/b7f3ab500153?raw)