OpenAI Decisions API 用量

2026-11-19 17:41 更新

Decisions API 用量

get /organization/usage/decisions

获取组织的 Decisions API 用量明细。

查询参数

  • start_time: integer

查询时间范围的起始时间(Unix 秒),包含该时刻。

  • api_key_ids: optional array of string or null

仅返回指定 API 密钥的用量。

  • batch: optional boolean or null

取值为 true 时,仅返回批处理任务。取值为 false 时,仅返回非批处理任务。默认两类均返回。

  • bucket_width: optional "1m" or "1h" or "1d" or null

响应中每个时间桶的时长。目前支持 1m、1h 和 1d,默认值为 1d。

  • "1m"

  • "1h"

  • "1d"

  • end_time: optional integer or null

查询时间范围的结束时间(Unix 秒),不包含该时刻。

  • group_by: optional array of "project_id" or "user_id" or "api_key_id" or 4 more or null

按指定字段对用量分组。可使用 project_id、user_id、api_key_id、model、batch、service_tier 和 api_source,也可组合使用。按 api_source 分组时,已归因的 Agents API 活动记为 agents_api,其他活动记为 unlabeled。未按来源分组时,api_source 为 null。

  • "project_id"

  • "user_id"

  • "api_key_id"

  • "model"

  • "batch"

  • "service_tier"

  • "api_source"

  • limit: optional integer or null

指定返回的时间桶数量。

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

  • models: optional array of string or null

仅返回指定模型的用量。

  • page: optional string or null

分页游标,对应上一页响应中的 next_page 字段。

  • project_ids: optional array of string or null

仅返回指定项目的用量。

  • user_ids: optional array of string or null

仅返回指定用户的用量。

返回值

  • data: array of object { end_time, object, results, start_time }

  • end_time: integer

  • object: "bucket" (default: "bucket")

  • "bucket"

  • results: array of object { input_tokens, num_model_requests, object, 22 more }

  • input_tokens: integer

输入词元总数,包括缓存命中和写入缓存的词元,涵盖文本、音频及图像。订阅 Scale Tier 的客户还会计入 Scale Tier 词元。

  • num_model_requests: integer

向模型发出的请求次数。

  • object: "organization.usage.decisions.result" (default: "organization.usage.decisions.result")

  • "organization.usage.decisions.result"

  • output_tokens: integer

文本、音频和图像输出的词元总数。

  • api_key_id: optional string or null

当 group_by=api_key_id 时,此字段给出该分组的 API 密钥 ID。

  • api_source: optional "agents_api" or "unlabeled" or null

按 api_source 分组时,agents_api 标识已归因的 Agents API 活动,unlabeled 包括所有未公布来源归因的记录,含历史记录和来源未知的记录。unlabeled 本身无法判定记录是否来自直接调用 API。未按来源分组时,此字段为 null。

  • "agents_api"

  • "unlabeled"

  • batch: optional boolean or null

当 group_by=batch 时,此字段表示该分组是否属于批处理用量。

  • input_audio_tokens: optional integer or null

未命中缓存的音频输入词元总数。

  • input_cache_write_12h_tokens: optional integer or null

写入缓存并保留 12 小时的输入词元总数。

  • input_cache_write_30m_tokens: optional integer or null

写入缓存并保留 30 分钟的输入词元总数。

  • input_cache_write_tokens: optional integer or null

写入缓存的输入词元总数,合计 30 分钟和 12 小时两个保留期。

  • input_cached_audio_tokens: optional integer or null

命中缓存的音频输入词元总数。

  • input_cached_image_tokens: optional integer or null

命中缓存的图像输入词元总数。

  • input_cached_text_tokens: optional integer or null

命中缓存的文本输入词元总数。

  • input_cached_tokens: optional integer or null

命中缓存的文本、音频和图像输入词元总数。订阅 Scale Tier 的客户还会计入 Scale Tier 词元。

  • input_image_tokens: optional integer or null

未命中缓存的图像输入词元总数。

  • input_text_tokens: optional integer or null

未命中缓存的文本输入词元总数,扣除写入缓存的词元。

  • input_uncached_tokens: optional integer or null

未命中缓存的文本、音频和图像输入词元总数,扣除写入缓存的词元。

  • model: optional string or null

当 group_by=model 时,此字段给出该分组的模型名称。

  • output_audio_tokens: optional integer or null

音频输出词元总数。

  • output_image_tokens: optional integer or null

图像输出词元总数。

  • output_text_tokens: optional integer or null

文本输出词元总数。

  • project_id: optional string or null

当 group_by=project_id 时,此字段给出该分组的项目 ID。

  • service_tier: optional string or null

当 group_by=service_tier 时,此字段给出该分组的服务层级。

  • user_id: optional string or null

当 group_by=user_id 时,此字段给出该分组的用户 ID。

  • start_time: integer

  • has_more: boolean

  • next_page: string or null

  • object: "page" (default: "page")

  • "page"

示例

## 从环境变量读取管理员密钥并查询组织用量,按项目和模型分组
curl --get "https://api.openai.com/v1/organization/usage/decisions" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  --data-urlencode "start_time=1790812800" \
  --data-urlencode "end_time=1790899200" \
  --data-urlencode "bucket_width=1d" \
  --data-urlencode "group_by=project_id" \
  --data-urlencode "group_by=model"

响应示例

{
    "object": "page",
    "data": [
        {
            "object": "bucket",
            "start_time": 1790812800,
            "end_time": 1790899200,
            "results": [
                {
                    "object": "organization.usage.decisions.result",
                    "input_tokens": 1000,
                    "input_cached_tokens": 400,
                    "output_tokens": 0,
                    "num_model_requests": 5,
                    "project_id": "proj_example",
                    "model": "gpt-6-luna",
                    "user_id": null,
                    "api_key_id": null,
                    "batch": null,
                    "service_tier": null
                }
            ]
        }
    ],
    "has_more": false,
    "next_page": null
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号