Formal Billing Statement API (v2.2)

Use this API to retrieve issued daily billing statement details and summaries for an enterprise account.

• Detail endpoint: GET /getDailyList
• Summary endpoint: GET /getDailySummary
• Authentication: enterprise-main-account billing read-only token
• Billing timezone: UTC+0
• Issuance: previous UTC calendar day at 02:00 UTC (10:00 Asia/Shanghai)
• Visibility: issued dates only

Base URLs

Environment	Base URL
Production	https://cubicspaces.cloud

Authentication

Both endpoints require a bill-... token owned by an enabled enterprise main account:

Authorization: Bearer bill-xxxxxxxxxxxxxxxx

The token is read-only and cannot call model APIs. Model API keys and billing tokens owned by personal accounts or enterprise sub-accounts are rejected.

List statement details

GET /getDailyList

Each row has the following grain:

billing day × API key × model × token type × currency × entry type

Query parameters

Parameter	Type	Required	Description
startDate	string	Yes	Inclusive first billing date in yyyy-MM-dd format
endDate	string	Yes	Inclusive last billing date in yyyy-MM-dd format
userId	integer	No	Account ID filter; the enterprise main ID keeps the whole enterprise scope
userName	string	No	Exact username filter; the enterprise main username keeps the whole enterprise scope
pageSize	integer	Yes	Rows per page, maximum 100
pageNum	integer	Yes	One-based page number

The maximum inclusive range is 92 billing days.

Request

curl --request GET \
  'https://cubicspaces.cloud/getDailyList?startDate=2026-07-22&endDate=2026-07-23&pageSize=100&pageNum=1' \
  --header 'Authorization: Bearer bill-xxxxxxxxxxxxxxxx'

Response

One model can produce multiple rows for different token types. Additional models produce additional rows:

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "key-production-a",
        "modelType": "claude",
        "modelName": "claude-opus-4-6",
        "tokenType": "textInputTokens",
        "tokenCount": "1200000",
        "tokenUnit": "piece",
        "currency": "USD",
        "subtotalBeforeTax": "3.60000000",
        "subtotalAfterDiscount": "3.09600000",
        "totalAmountAfterTax": "3.09600000",
        "discountDetail": {
          "type": "contract",
          "rate": "0.86000000",
          "amount": "0.50400000"
        }
      },
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "key-image-production",
        "modelType": "gemini",
        "modelName": "gemini-3.1-flash-image-preview",
        "tokenType": "imageOutputTokens",
        "tokenCount": "12",
        "tokenUnit": "piece",
        "currency": "USD",
        "subtotalBeforeTax": "0.48000000",
        "subtotalAfterDiscount": "0.48000000",
        "totalAmountAfterTax": "0.48000000"
      }
    ]
  }
}

Detail fields

Field	Required	Description
billMonth	Yes	Billing month in yyyyMM format
billDay	Yes	Billing date in yyyy-MM-dd format
billingDateTimezone	Yes	Always utc+0
account	Yes	API key name captured at issuance; legacy details without a key name fall back to the account username and then the stored account identifier
modelType	Yes	Model category, such as claude, gemini, or gpt
modelName	Yes	Full model name
tokenType	Yes	Token or usage category
tokenCount	Yes	Usage count; negative for refunds
tokenUnit	Yes	Always piece
currency	Yes	Currency
subtotalBeforeTax	Yes	Before-discount, before-tax amount with eight decimal places
subtotalAfterDiscount	Yes	After-discount, before-tax amount with eight decimal places
totalAmountAfterTax	Yes	After-discount, after-tax amount with eight decimal places
entryType	No	Omitted for normal usage; refund for refunds
discountDetail	No	Returned when a contract discount applies

Supported token types are:

• textInputTokens, textOutputTokens
• imageInputTokens, imageOutputTokens
• videoInputTokens, videoOutputTokens
• audioInputTokens, audioOutputTokens
• cacheCreationTokens5m, cacheCreationTokens1h, cacheTokens
• reasoningTokens

Only categories with recorded usage are returned. The API does not fabricate every category for every model.

data.provider is optional. It is omitted when one reliable model or inference provider cannot be determined. It is never an empty string and never substitutes the platform name for the model provider.

The current version does not return price. Use the three amount fields as authoritative.

In the detail endpoint, account distinguishes API keys. Multiple keys under one direct account therefore appear in separate detail rows. The userId and userName request parameters still filter enterprise accounts. /getDailySummary is not split by API key and continues to return account-level summaries, so its account value remains the account username or stored identifier.

List daily summaries

GET /getDailySummary

Summary rows have this grain:

billing day × account × currency

The query parameters are the same as /getDailyList, except that the maximum range is 366 inclusive days and pageSize is capped at 400.

curl --request GET \
  'https://cubicspaces.cloud/getDailySummary?startDate=2026-07-01&endDate=2026-07-23&pageSize=100&pageNum=1' \
  --header 'Authorization: Bearer bill-xxxxxxxxxxxxxxxx'

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "enterprise-subaccount",
        "currency": "USD",
        "subtotalBeforeTax": "4.08000000",
        "subtotalAfterDiscount": "3.57600000",
        "totalAmountAfterTax": "3.57600000",
        "entryCount": 2
      }
    ]
  }
}

entryCount is the number of matching detail rows. Summary amounts equal the sum of matching detail amounts, including negative refund rows.

Issuance and data rules

• Billing dates always use UTC+0; the request cannot change the timezone.
• The previous UTC calendar day's statement is issued daily at 02:00 UTC (10:00 Asia/Shanghai).
• A query range may include unissued dates, but only issued dates are returned.
• No matching data returns total: 0 and rows: [].
• Historical statements keep the model category, discount, and settled amounts captured at issuance. Later price changes do not reprice them.

Rate limit

Requests are limited by enterprise main account, not source IP. The default limit is 120 requests per 60 seconds.

HTTP 429 responses include Retry-After with the minimum number of seconds to wait.

Status codes

HTTP status	Description
200	Success
400	Missing or invalid parameters, invalid date format, or excessive range
401	Missing, invalid, expired, reset, or wrong token type, or disabled token owner
403	The valid token does not belong to an enterprise main account
429	Enterprise-account rate limit exceeded
500	Internal server or database error
503	Maintenance or formal billing service temporarily unavailable

All errors use this envelope:

{
  "code": 40001,
  "message": "startDate is invalid, expected format: yyyy-MM-dd",
  "data": {}
}

Integration recommendations

1. Use /getDailySummary for daily payable totals.
2. Use /getDailyList for model and token-type reconciliation.
3. Treat billDay + account + modelName + tokenType + currency + entryType as the detail idempotency key; treat an omitted entryType as normal.
4. Parse amounts as decimal fixed-point values, not binary floating-point numbers.
5. Use the returned amounts and discounts instead of repricing historical statements with current model prices.