2026-10-22
Loading…| Fact | Detail |
|---|---|
| The organization is the key | The caller's API key resolves to exactly one organization; no organization id appears in any path, and any valid key of the organization can read this domain |
| Actual charges only | What the organization was actually charged, in its settlement currency (CNY or USD); promotional balance is taken before cash and is included |
| Column names follow FOCUS 1.3 | BilledCost, ServiceName, ConsumedQuantity and the rest match the FOCUS 1.3 specification verbatim |
| Everything is UTC | Window bounds and buckets are UTC ISO 8601; buckets align to the hour or the UTC day |
| Windows cap at 93 days | Costs, usage and events accept at most 93 days per query; for longer ranges use the charges export, which paginates day by day server-side |
| Pagination is an opaque cursor | Lists carry has_more and next_page; pass next_page back as page unchanged |
Amounts are decimal strings (e.g. "0.001234") in the currency named by BillingCurrency on the same row (CNY or USD) — don't sum them as floats, and never add amounts of different currencies; reconcile with exact decimal arithmetic.
Only usage billed in USD from the funding account is counted here; Credits balances are not part of this domain. See Authentication for how keys work.
| Method | Path | Description | Support |
|---|---|---|---|
| GET | /v1/costs | List costs | ● Supported |
| GET | /v1/usage | List usage | ● Supported |
| GET | /v1/events | List usage events | ● Supported |
| GET | /v1/events/{id} | Get a usage event | ● Supported |
| GET | /v1/charges | Export charges | ● Supported |
For authoritative parameters and fields, see the spec published at /meta/v1/openapi.yaml and the FOCUS 1.3 specification.
Errors follow the problem+json format, see errors; quotas and response headers are covered in rate limits.
/organization/v1/costs● Supportedstarting_atstring必填query: Window start (inclusive), UTC ISO 8601, e.g. 2026-09-26T00:00:00Z
ending_atstring必填query: Window end (exclusive), UTC ISO 8601; at most 93 days after starting_at (the charges export has no such cap)
bucket_widthstring必填query: Bucket width: 1h (aligned to the hour) or 1d (aligned to the UTC day)
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: Columns to group by (repeatable): ServiceName, ServiceCategory, ResourceId, ConsumedUnit; usage always splits ConsumedUnit out server-side
pagestring可选query: The opaque cursor from the previous page's next_page — pass it back unchanged
200 page
Errors follow the problem+json format — see error codes
Cost page
application/json
| Name | Type | Description |
|---|---|---|
| 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`. |
| Field | Description |
|---|---|
object | always "page" |
data[].object | always "bucket" |
data[].starting_at / data[].ending_at | Bucket start and end (UTC, aligned to the hour or the day) |
data[].estimated | Always false: a charge is final when it is recorded; kept to match the AWS GetCostAndUsage shape |
data[].results[].ServiceName | Serving service name (present only when group_by requests ServiceName) |
data[].results[].ServiceCategory | FOCUS service category (present only when requested) |
data[].results[].ResourceId / data[].results[].ResourceName | Resource id and display name; ResourceName rides ResourceId and falls back to the id when unresolvable |
data[].results[].BilledCost | The group's cost in the bucket, a decimal string in BillingCurrency |
data[].results[].BillingCurrency | The currency charged, CNY or USD; a group charged in both currencies in one bucket is two rows |
has_more / next_page | Whether more pages follow; the next page's opaque cursor (null when done) |
For the transactions behind one event see Get a usage event.
/organization/v1/usage● Supportedstarting_atstring必填query: Window start (inclusive), UTC ISO 8601, e.g. 2026-09-26T00:00:00Z
ending_atstring必填query: Window end (exclusive), UTC ISO 8601; at most 93 days after starting_at (the charges export has no such cap)
bucket_widthstring必填query: Bucket width: 1h (aligned to the hour) or 1d (aligned to the UTC day)
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: Columns to group by (repeatable): ServiceName, ServiceCategory, ResourceId, ConsumedUnit; usage always splits ConsumedUnit out server-side
pagestring可选query: The opaque cursor from the previous page's next_page — pass it back unchanged
200 page
Errors follow the problem+json format — see error codes
Usage page
application/json
| Name | Type | Description |
|---|---|---|
| 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`. |
| Field | Description |
|---|---|
object / data[].object | always "page" / always "bucket" |
data[].starting_at / data[].ending_at / data[].estimated | Bucket start/end (UTC) and the estimated marker (always false), same as costs |
data[].results[].ServiceName / ServiceCategory | Service columns (present only when requested) |
data[].results[].ResourceId / data[].results[].ResourceName | Resource columns; ResourceName rides ResourceId |
data[].results[].ConsumedQuantity | The group's consumed quantity, a decimal string |
data[].results[].ConsumedUnit | The consumption unit; different units stay on separate rows and are never added together |
has_more / next_page | Cursor pagination, same as costs |
For the transactions behind one event see Get a usage event.
/organization/v1/events● Supportedstarting_atstring必填query: Window start (inclusive), UTC ISO 8601, e.g. 2026-09-26T00:00:00Z
ending_atstring必填query: Window end (exclusive), UTC ISO 8601; at most 93 days after starting_at (the charges export has no such cap)
limitinteger可选query: Page size, 1–100, defaults to 25
pagestring可选query: The opaque cursor from the previous page's next_page — pass it back unchanged
200 page
Errors follow the problem+json format — see error codes
Event page
application/json
| Name | Type | Description |
|---|---|---|
| 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`. |
| Field | Description |
|---|---|
object | always "page" |
data[].object | always "usage.event" |
data[].id | The event id — use it for the single-event lookup and reconciliation |
data[].occurred_at | When the usage happened (UTC) |
data[].ServiceName / ServiceCategory / ResourceId / ResourceName | FOCUS service and resource columns |
data[].BilledCost / BillingCurrency | The event's cost (decimal string) and the currency charged (CNY or USD) |
data[].ChargeClass | "Correction" for correction events (negative cost), null otherwise |
data[].request_id | The X-Request-Id of the API call that produced this usage — look it up in your call logs |
data[].settlement.status | settled (charged) / no_charge (recorded, nothing charged) / rejected (billing refused the charge) |
data[].settlement.shortfall / data[].settlement.zero_reason | Currently always null; reserved for later settlement detail |
has_more / next_page | Newest first, one cursor page at a time; pages never duplicate or skip an event |
For the transactions behind one event see Get a usage event.
/organization/v1/events/{id}● Supportedidstring必填path: The usage event id from the events list's data[].id
200 usage.event
Errors follow the problem+json format — see error codes
The usage event
application/json
| Name | Type | Description |
|---|---|---|
| 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. |
| Field | Description |
|---|---|
object / id / occurred_at | always "usage.event", the event id, when it happened (UTC) |
ServiceName / ServiceCategory / ResourceId / ResourceName / BilledCost / BillingCurrency / ChargeClass / request_id / settlement | Exactly the same fields the events list carries for this event |
lines[].meter / lines[].display_name | The meter's identifier and its English display name |
lines[].ConsumedQuantity / ConsumedUnit | The line's consumed quantity and unit |
lines[].ListUnitPrice / PricingUnit | Always null: an event is priced as a whole, so there is no per-line unit price |
lines[].BilledCost | The line's cost, equal to the event's BilledCost |
x_Charges[] | The transactions that paid this event: transaction_id, BilledCost, BillingCurrency and sub_account (promotional balance or cash; promotional is taken first). They add up to the event's BilledCost |
For the transactions behind one event see Get a usage event.
/organization/v1/charges● Supportedstarting_atstring必填query: Window start (inclusive), UTC ISO 8601, e.g. 2026-09-26T00:00:00Z
ending_atstring必填query: Window end (exclusive), UTC ISO 8601; at most 93 days after starting_at (the charges export has no such cap)
200
Errors follow the problem+json format — see error codes
FOCUS 1.3 JSONL stream
application/x-ndjson
| Name | Type | Description |
|---|---|---|
| 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. |
| Field | Description |
|---|---|
ChargePeriodStart / ChargePeriodEnd | Charge period start and end (UTC) |
BilledCost / BillingCurrency | The event's cost (decimal string) and the currency charged (CNY or USD) |
ServiceName / ServiceCategory / ResourceId / ResourceName | FOCUS service and resource columns |
ConsumedQuantity / ConsumedUnit | Consumed quantity and unit |
ChargeCategory | Usage or Adjustment |
ChargeClass | "Correction" for corrections, null otherwise |
ChargeDescription | A human-readable description of the meter |
x_RequestId / x_EventId | The X-Request-Id of the call behind this record; the matching usage event id |
For the transactions behind one event see Get a usage event.