List Usage Details
POST/openapi/v1/bill/usage/detail
Query the usage details (per sub-customer) under the current application's billing space (OwnerSpaceId). Filtering by time range, sub-customer space, and quota type is supported, with pagination.
Permission
- Requires OAuth Bearer token with the bill:manage scope granted.
Mandatory Constraints
- OwnerSpaceId is injected by the server from the current AppID via oauth_apps.owner_space_id. Callers must not pass this field.
- StartTime / EndTime are RFC3339 time strings (timezone offset required); the range must not exceed 31 days.
- Limit defaults to 20, with a maximum of 50.
Aggregation Rules - Only records whose action is in (pay, deduct) are counted.
Request Parameters
Header Parameters
AuthorizationRequiredstring
Bearer <access_token>
Request Body
application/jsonStartTimeRequiredstring(date-time)
Query start time in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) format (timezone offset is required; UTC is recommended), e.g. `2026-06-01T00:00:00Z`. Required.
EndTimeRequiredstring(date-time)
Query end time in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) format (timezone offset is required; UTC is recommended), e.g. `2026-06-30T23:59:59Z`. Required. Requires `StartTime` ≤ `EndTime` and the range must not exceed 31 days.
SpaceIdOptionalstring
Space ID. **Optional**.
- **Omitted**: Defaults to the space that the current access_token belongs to (i.e. the primary account space bound to the application), and returns its billing data.
- **Provided**: Returns billing data for the specified sub-customer space. Useful for third-party integrations that need per-sub-customer reconciliation.
QuotaTypeOptionalstring
Quota type (optional). Filter by quota dimension. Supported values include `ses` (SMS), `ekyc` (identity verification), `member` (member seat), etc.
OffsetOptionalinteger(int32)
Pagination offset (optional), defaults to `0`.
LimitOptionalinteger(int32)
Page size (optional), defaults to `20`, maximum `50`.
Response Parameters
Response.Data
DetailsOptionalarray<object>
Usage detail array
OccurredAtOptionalstring(date-time)
Time when the consumption occurred, in RFC3339 format (**UTC**, ending with `Z`), e.g. `2026-06-01T02:23:45Z`.
SpaceIdOptionalstring
Sub-customer Space ID that owns this consumption
UserIdOptionalstring
Operator user ID that triggered the consumption
SpaceNameOptionalstring
Sub-customer company name (filled by the server; may be empty if the lookup fails)
EnvelopeIdOptionalstring
Related envelope ID (if the consumption comes from an envelope flow)
EnvelopeNameOptionalstring
Related envelope name (filled by the server; may be empty if the lookup fails)
UsageTypeOptionalstring
Usage type (matches the QuotaType dimension, e.g. `ses` / `ekyc` / `member`)
PackageNameOptionalstring
Package spec name (e.g. resource pack SKU key)
QuantityOptionalinteger(int64)
Consumption quantity of this record
TotalOptionalinteger(int64)
Total number of records matching the filter
Error Codes
| Error Code | Description |
|---|---|
INVALID_REQUEST | Invalid parameters (missing StartTime / EndTime, bad format, or range exceeds limit) |
UNAUTHORIZED | access_token missing, invalid or expired |
FORBIDDEN | Scope does not include bill:manage |
INTERNAL_ERROR | Internal server error |