2026-10-20
加载中…| 事实 | 说明 |
|---|---|
| 组织由 Key 决定 | 调用方的 API Key 解析出唯一的组织；路径里没有组织 ID，组织的任何有效 API Key 都可读本域 |
| 只覆盖实际扣费 | 统计组织实际被扣的费用，按结算币种（人民币 CNY 或美元 USD）计；组织的赠送额度先于现金被扣，也在其中 |
| 字段名按 FOCUS 1.3 | BilledCost、ServiceName、ConsumedQuantity 等列名与 FOCUS 1.3 规范逐字一致 |
| 时间一律 UTC | 窗口边界与时间桶都是 UTC ISO 8601；桶对齐到整点或自然日 |
| 查询窗口上限 93 天 | 查询费用 / 查询用量 / 用量事件一次最多查 93 天；更久的账用费用明细导出，它按天在服务端分页 |
| 分页是不透明游标 | 列表带 has_more 与 next_page；把 next_page 原样放进 page 参数取下一页 |
金额都是十进制字符串（如 "0.001234"），币种见同一行的 BillingCurrency（CNY 或 USD）；不要用浮点数相加——对账请按字符串精确十进制求和，且不同币种不要相加。
这里只统计从资金账户以美元扣费的用量；Credits 余额不在这个域。鉴权方式见鉴权。
| 方法 | 路径 | 说明 | 支持 |
|---|---|---|---|
| GET | /v1/costs | 查询费用 | ● 支持 |
| GET | /v1/usage | 查询用量 | ● 支持 |
| GET | /v1/events | 列出用量事件 | ● 支持 |
| GET | /v1/events/{id} | 查看单个用量事件 | ● 支持 |
| GET | /v1/charges | 导出费用明细 | ● 支持 |
参数与字段的权威定义以本站 /meta/v1/openapi.yaml 公开的规范与 FOCUS 1.3 规范为准。
/organization/v1/costs● 支持starting_atstring必填query: 窗口开始（含），UTC ISO 8601，如 2026-09-26T00:00:00Z
ending_atstring必填query: 窗口结束（不含），UTC ISO 8601；距 starting_at 最多 93 天（费用明细导出无此限制）
bucket_widthstring必填query: 时间桶宽度：1h（整点对齐）或 1d（自然日对齐），一律 UTC
time_zonestring可选query: IANA time zone name (for example Asia/Shanghai) whose local hours or days form the buckets. Defaults to UTC. Offsets such as +08:00 are rejected. The window widens to whole local buckets; a day that crosses a daylight-saving change lasts 23 or 25 hours. starting_at and ending_at stay UTC instants.
group_byarray可选query: 分组列，可重复：ServiceName、ServiceCategory、ResourceId、ConsumedUnit；查询用量时 ConsumedUnit 恒被服务端拆出
pagestring可选query: 上一页响应里 next_page 给出的不透明游标，原样带回即可
200 page
错误按 problem+json 格式返回，参见 错误码
Cost page
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `page`. |
| data | array<object> | Cost buckets in time order, one per hour or day of the requested window. |
| data[].object | string | Object type; always `bucket`. |
| data[].starting_at | string | Start of the bucket, UTC, inclusive. |
| data[].ending_at | string | End of the bucket, UTC, exclusive. |
| data[].estimated | boolean | Always false; kept for the AWS GetCostAndUsage shape. |
| data[].results | array<object> | Aggregates of the bucket, one entry per group requested with group_by. |
| has_more | boolean | Whether more results exist beyond this page; request again with `page` set to `next_page` to read them. |
| next_page | string | null | Opaque cursor for the next page; null on the last page. Pass it unchanged as `page`. |
| 字段 | 说明 |
|---|---|
object | 固定 "page" |
data[].object | 固定 "bucket" |
data[].starting_at / data[].ending_at | 桶的起止时间（UTC，整点或自然日对齐） |
data[].estimated | 恒为 false：费用入账即为最终金额；保留该字段是为了与 AWS GetCostAndUsage 的形状一致 |
data[].results[].ServiceName | 产生用量的服务名（仅在请求 group_by 含 ServiceName 时出现） |
data[].results[].ServiceCategory | FOCUS 服务类别（仅按请求出现） |
data[].results[].ResourceId / data[].results[].ResourceName | 资源 ID 与显示名；ResourceName 随 ResourceId 附带，解析不到显示名时等于 ResourceId |
data[].results[].BilledCost | 该桶该组的费用，十进制字符串，币种见 BillingCurrency |
data[].results[].BillingCurrency | 扣费币种，CNY 或 USD；同一组在一个桶里用过两种币种时分成两行 |
has_more / next_page | 是否还有下一页；下一页的不透明游标（null 表示没有更多） |
支付一个事件的交易明细见查看单个用量事件。
/organization/v1/usage● 支持starting_atstring必填query: 窗口开始（含），UTC ISO 8601，如 2026-09-26T00:00:00Z
ending_atstring必填query: 窗口结束（不含），UTC ISO 8601；距 starting_at 最多 93 天（费用明细导出无此限制）
bucket_widthstring必填query: 时间桶宽度：1h（整点对齐）或 1d（自然日对齐），一律 UTC
time_zonestring可选query: IANA time zone name (for example Asia/Shanghai) whose local hours or days form the buckets. Defaults to UTC. Offsets such as +08:00 are rejected. The window widens to whole local buckets; a day that crosses a daylight-saving change lasts 23 or 25 hours. starting_at and ending_at stay UTC instants.
group_byarray可选query: 分组列，可重复：ServiceName、ServiceCategory、ResourceId、ConsumedUnit；查询用量时 ConsumedUnit 恒被服务端拆出
pagestring可选query: 上一页响应里 next_page 给出的不透明游标，原样带回即可
200 page
错误按 problem+json 格式返回，参见 错误码
Usage page
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `page`. |
| data | array<object> | Usage buckets in time order, one per hour or day of the requested window. |
| data[].object | string | Object type; always `bucket`. |
| data[].starting_at | string | Start of the bucket, UTC, inclusive. |
| data[].ending_at | string | End of the bucket, UTC, exclusive. |
| data[].estimated | boolean | Always false; kept for the AWS GetCostAndUsage shape. |
| data[].results | array<object> | Aggregates of the bucket, one entry per group requested with group_by. |
| has_more | boolean | Whether more results exist beyond this page; request again with `page` set to `next_page` to read them. |
| next_page | string | null | Opaque cursor for the next page; null on the last page. Pass it unchanged as `page`. |
| 字段 | 说明 |
|---|---|
object / data[].object | 固定 "page" / 固定 "bucket" |
data[].starting_at / data[].ending_at / data[].estimated | 桶的起止（UTC）与 estimated 标记（恒为 false），与查询费用相同 |
data[].results[].ServiceName / ServiceCategory | 服务列（仅按请求出现） |
data[].results[].ResourceId / data[].results[].ResourceName | 资源列；ResourceName 随 ResourceId 附带 |
data[].results[].ConsumedQuantity | 该桶该组的消耗数量，十进制字符串 |
data[].results[].ConsumedUnit | 计量单位；不同单位各成一行，永远不会相加 |
has_more / next_page | 游标分页，与查询费用相同 |
支付一个事件的交易明细见查看单个用量事件。
/organization/v1/events● 支持starting_atstring必填query: 窗口开始（含），UTC ISO 8601，如 2026-09-26T00:00:00Z
ending_atstring必填query: 窗口结束（不含），UTC ISO 8601；距 starting_at 最多 93 天（费用明细导出无此限制）
limitinteger可选query: 每页条数，1–100，默认 25
pagestring可选query: 上一页响应里 next_page 给出的不透明游标，原样带回即可
200 page
错误按 problem+json 格式返回，参见 错误码
Event page
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `page`. |
| data | array<object> | Usage events, newest first. |
| data[].object | string | Object type; always `usage.event`. |
| data[].id | string | Id of the usage event; pass it to getOrganizationEvent. |
| data[].occurred_at | string | Time at which the usage happened, UTC. |
| data[].ServiceName | string | Name of the platform service that produced the usage (the source service of the usage event). |
| data[].ServiceCategory | string | Category of the service; a service without a registered category reports its own name. |
| data[].ResourceId | string | Id of the resource that the usage belongs to. |
| data[].ResourceName | string | Display name of the resource; falls back to ResourceId when no name is known. |
| data[].BilledCost | string | Amount billed in USD as an exact decimal string; unsettled usage counts as 0 until it settles. |
| data[].BillingCurrency | string | Currency of BilledCost; always `USD`. |
| data[].ChargeClass | string | null | `Correction` for an event that corrects an earlier charge (its BilledCost is negative); null for ordinary usage. |
| data[].request_id | string | null | X-Request-Id of the API call that produced the usage; null for usage that does not come from a request. |
| data[].settlement | object | How the usage was charged: settlement state, any shortfall, and why nothing was charged. |
| data[].lines | array<object> | Metering lines mapped from the billing measurements; the priced split (ListUnitPrice, PricingUnit, BilledCost) rides only GET /events/{id}. |
| has_more | boolean | Whether more results exist beyond this page; request again with `page` set to `next_page` to read them. |
| next_page | string | null | Opaque cursor for the next page; null on the last page. Pass it unchanged as `page`. |
| 字段 | 说明 |
|---|---|
object | 固定 "page" |
data[].object | 固定 "usage.event" |
data[].id | 事件 id；查单条明细、对账都用它 |
data[].occurred_at | 事件发生时间（UTC） |
data[].ServiceName / ServiceCategory / ResourceId / ResourceName | FOCUS 服务与资源列 |
data[].BilledCost / BillingCurrency | 事件费用（十进制字符串）与扣费币种（CNY 或 USD） |
data[].ChargeClass | 更正事件为 "Correction"（费用为负数），普通事件为 null |
data[].request_id | 产生这次用量的那次 API 调用响应头 X-Request-Id 的值，可拿去调用日志里查同一次请求 |
data[].settlement.status | settled（已扣费）/ no_charge（已记录，不收费）/ rejected（计费拒绝了这次扣费） |
data[].settlement.shortfall / data[].settlement.zero_reason | 目前恒为 null，保留给之后的结算细节 |
has_more / next_page | 按发生时间倒序逐页；游标不透明，不重复、不遗漏 |
支付一个事件的交易明细见查看单个用量事件。
/organization/v1/events/{id}● 支持idstring必填path: 用量事件 id，来自用量事件列表的 data[].id
200 usage.event
错误按 problem+json 格式返回，参见 错误码
The usage event
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| object | string | Object type; always `usage.event`. |
| id | string | Id of the usage event; pass it to getOrganizationEvent. |
| occurred_at | string | Time at which the usage happened, UTC. |
| ServiceName | string | Name of the platform service that produced the usage (the source service of the usage event). |
| ServiceCategory | string | Category of the service; a service without a registered category reports its own name. |
| ResourceId | string | Id of the resource that the usage belongs to. |
| ResourceName | string | Display name of the resource; falls back to ResourceId when no name is known. |
| BilledCost | string | Amount billed in USD as an exact decimal string; unsettled usage counts as 0 until it settles. |
| BillingCurrency | string | Currency of BilledCost; always `USD`. |
| ChargeClass | string | null | `Correction` for an event that corrects an earlier charge (its BilledCost is negative); null for ordinary usage. |
| request_id | string | null | X-Request-Id of the API call that produced the usage; null for usage that does not come from a request. |
| settlement | object | How the usage was charged: settlement state, any shortfall, and why nothing was charged. |
| settlement.status | string | Settlement state of the event. |
| settlement.shortfall | string | null | USD amount that could not be charged, as a decimal string, when status is settled_with_shortfall; null otherwise. |
| settlement.zero_reason | string | null | Why nothing was charged for the event: `byok` when the caller used its own provider key; null when a charge applies. |
| lines | array<object> | Priced lines of the event; their BilledCost values add up to the event's BilledCost. |
| lines[].meter | string | Key of the meter that measured the line. |
| lines[].display_name | string | English label of the meter; falls back to the meter key in list pages. |
| lines[].ConsumedQuantity | string | Quantity consumed, an exact decimal string in ConsumedUnit. |
| lines[].ConsumedUnit | string | Unit of ConsumedQuantity as reported by the metering line; quantities of different units are never added together. |
| lines[].ListUnitPrice | string | null | List price in USD per PricingUnit as a decimal string; null when the line is not priced. |
| lines[].PricingUnit | string | null | Unit that ListUnitPrice applies to; null when the line is not priced. |
| lines[].BilledCost | string | Amount billed for this line in USD as a decimal string. |
| x_Charges | array<object> | The transactions that paid this event; their BilledCost sums to the event's BilledCost. |
| x_Charges[].transaction_id | string | The id of the billing transaction that paid part of this event. |
| x_Charges[].BilledCost | string | Amount billed in USD as an exact decimal string; unsettled usage counts as 0 until it settles. |
| x_Charges[].BillingCurrency | string | Currency of BilledCost; always `USD`. |
| x_Charges[].sub_account | string | Which balance the transaction was taken from. |
| 字段 | 说明 |
|---|---|
object / id / occurred_at | 固定 "usage.event"、事件 id、发生时间（UTC） |
ServiceName / ServiceCategory / ResourceId / ResourceName / BilledCost / BillingCurrency / ChargeClass / request_id / settlement | 与用量事件列表中同一事件完全相同的字段 |
lines[].meter / lines[].display_name | 计量项标识与其英文显示名 |
lines[].ConsumedQuantity / ConsumedUnit | 该计量项的消耗数量与单位 |
lines[].ListUnitPrice / PricingUnit | 恒为 null：计费按整个事件定价，没有逐计量项的单价 |
lines[].BilledCost | 该计量项的费用，等于事件的 BilledCost |
x_Charges[] | 支付这个事件的交易：transaction_id、BilledCost、BillingCurrency，以及 sub_account（promotional 赠送额度或 cash 现金；赠送额度先扣）。各笔相加等于事件的 BilledCost |
支付一个事件的交易明细见查看单个用量事件。
/organization/v1/charges● 支持starting_atstring必填query: 窗口开始（含），UTC ISO 8601，如 2026-09-26T00:00:00Z
ending_atstring必填query: 窗口结束（不含），UTC ISO 8601；距 starting_at 最多 93 天（费用明细导出无此限制）
200
错误按 problem+json 格式返回，参见 错误码
FOCUS 1.3 JSONL stream
application/x-ndjson
| 名称 | 类型 | 说明 |
|---|---|---|
| ChargePeriodStart | string | Start of the charge period (the event time), UTC. |
| ChargePeriodEnd | string | End of the charge period (the event time), UTC. |
| BilledCost | string | Amount billed in USD as an exact decimal string; unsettled usage counts as 0 until it settles. |
| BillingCurrency | string | Currency of BilledCost; always `USD`. |
| ServiceName | string | Name of the platform service that produced the usage (the source service of the usage event). |
| ServiceCategory | string | Category of the service; a service without a registered category reports its own name. |
| ResourceId | string | Id of the resource that the usage belongs to. |
| ResourceName | string | Display name of the resource; falls back to ResourceId when no name is known. |
| ConsumedQuantity | string | Quantity consumed, an exact decimal string in ConsumedUnit. |
| ConsumedUnit | string | Unit of ConsumedQuantity as reported by the metering line; quantities of different units are never added together. |
| ChargeCategory | string | Kind of charge. |
| ChargeClass | string | null | `Correction` for an event that corrects an earlier charge (its BilledCost is negative); null for ordinary usage. |
| ChargeDescription | string | Text such as `<service>/<offering> usage` that says what was charged. |
| x_RequestId | string | null | Always null in the export; look up the request id of an event with getOrganizationEvent. |
| x_EventId | string | Id of the usage event this record comes from; pass it to getOrganizationEvent. |
| 字段 | 说明 |
|---|---|
ChargePeriodStart / ChargePeriodEnd | 计费周期起止（UTC） |
BilledCost / BillingCurrency | 该事件费用（十进制字符串）与扣费币种（CNY 或 USD） |
ServiceName / ServiceCategory / ResourceId / ResourceName | FOCUS 服务与资源列 |
ConsumedQuantity / ConsumedUnit | 消耗数量与计量单位 |
ChargeCategory | Usage（用量）或 Adjustment（调整） |
ChargeClass | 更正记录为 "Correction"，普通记录为 null |
ChargeDescription | 计量项的人类可读描述 |
x_RequestId / x_EventId | 产生这条记录的 API 调用的 X-Request-Id；对应的用量事件 id |
支付一个事件的交易明细见查看单个用量事件。