# 组织 API (/docs/api/native/organization)



## 基础地址 [#基础地址]

<ApiBaseDomain prefix="/organization/v1" />

## 接入 [#接入]

<QuickstartTabs snippets="{&#x22;curl&#x22;:&#x22;curl \&#x22;https://api-origin.invalid/organization/v1/costs?starting_at=2026-09-26T00:00:00Z&ending_at=2026-09-27T00:00:00Z&bucket_width=1d&group_by=ServiceName\&#x22; \\\n  -H \&#x22;Authorization: Bearer $PRAXIS_API_KEY\&#x22;&#x22;,&#x22;python&#x22;:&#x22;import os\n\nimport requests\n\nopts = dict(\n    base_url=\&#x22;https://api-origin.invalid/organization/v1\&#x22;,\n    api_key=os.environ[\&#x22;PRAXIS_API_KEY\&#x22;],\n)\n\n# /organization 是我们自己的组织用量形状，直接发 HTTP 请求（Bearer 认证）\nresp = requests.get(\n    f\&#x22;{opts['base_url']}/costs?starting_at=2026-09-26T00:00:00Z&ending_at=2026-09-27T00:00:00Z&bucket_width=1d&group_by=ServiceName\&#x22;,\n    headers={\&#x22;Authorization\&#x22;: f\&#x22;Bearer {opts['api_key']}\&#x22;},\n)\nprint(resp.status_code, resp.json())&#x22;,&#x22;typescript&#x22;:&#x22;\n\nconst opts = {\n  baseURL: \&#x22;https://api-origin.invalid/organization/v1\&#x22;,\n  apiKey: process.env.PRAXIS_API_KEY,\n};\n\n// /organization 是我们自己的组织用量形状，直接发 HTTP 请求（Bearer 认证）\nconst resp = await fetch(`${opts.baseURL}/costs?starting_at=2026-09-26T00:00:00Z&ending_at=2026-09-27T00:00:00Z&bucket_width=1d&group_by=ServiceName`, {\n  headers: { Authorization: `Bearer ${opts.apiKey}` },\n});\nconsole.log(resp.status, await resp.json());&#x22;}" />

## 事实与边界 [#事实与边界]

| 事实             | 说明                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| 组织由 Key 决定     | 调用方的 API Key 解析出唯一的组织；路径里没有组织 ID，组织的任何有效 API Key 都可读本域                                                        |
| 只覆盖资金账户扣费      | 仅统计从资金账户以 USD 扣费的用量；Credits 不在统计内                                                                             |
| 字段名按 FOCUS 1.3 | BilledCost、ServiceName、ConsumedQuantity 等列名与 [FOCUS 1.3 规范](https://focus.finops.org/)逐字一致                    |
| 时间一律 UTC       | 窗口边界与时间桶都是 UTC ISO 8601；桶对齐到整点或自然日                                                                            |
| 查询窗口上限 93 天    | 查询费用 / 查询用量 / 用量事件一次最多查 93 天；更久的账用[费用明细导出](/docs/api/native/organization/exportOrganizationCharges)，它按天在服务端分页 |
| 分页是不透明游标       | 列表带 `has_more` 与 `next_page`；把 `next_page` 原样放进 `page` 参数取下一页                                                 |

金额都是美元十进制字符串（如 `"0.001234"`），不要用浮点数相加——对账请按字符串精确十进制求和。

这里只统计从资金账户以美元扣费的用量；Credits 余额不在这个域。鉴权方式见[鉴权](/docs/api/authentication)。

## 端点 [#端点]

| 方法  | 路径                                                                       | 说明       | 支持   |
| --- | ------------------------------------------------------------------------ | -------- | ---- |
| GET | [`/v1/costs`](/docs/api/native/organization/listOrganizationCosts)       | 查询费用     | ● 支持 |
| GET | [`/v1/usage`](/docs/api/native/organization/listOrganizationUsage)       | 查询用量     | ● 支持 |
| GET | [`/v1/events`](/docs/api/native/organization/listOrganizationEvents)     | 列出用量事件   | ● 支持 |
| GET | [`/v1/events/{id}`](/docs/api/native/organization/getOrganizationEvent)  | 查看单个用量事件 | ● 支持 |
| GET | [`/v1/charges`](/docs/api/native/organization/exportOrganizationCharges) | 导出费用明细   | ● 支持 |

## 与官方的差异 [#与官方的差异]

* 聚合信封照 OpenAI organization usage/costs、分桶与 estimated 标记照 AWS GetCostAndUsage、列名按 FOCUS 1.3、明细导出照 Vercel charges 的 JSONL。只给原始事实：占比、环比、前 N 名等派生视图不在本域，请在调用方自行计算。

参数与字段的权威定义以本站 [`/meta/v1/openapi.yaml`](/docs/api/native/meta/healthCheck) 公开的规范与 [FOCUS 1.3 规范](https://focus.finops.org/)为准。

错误按 problem+json 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。