Sign in
latestOpenAPI 3.1.02026-08-211061591.1 MB

69a962f1578f

Billing

Usage Billing Usage Summary

Total the caller's settled usage over a window.

/history is a ledger with one row per movement, so a total spanning more than one page cannot come from it. This answers the one question the UI asks of the whole ledger at once: how many runs, and what they cost.

Only settled usage counts. void, expiry and chargeback draw the balance down as well, but they reverse a grant rather than report usage.

get/api/v1/usage_billing/usage_summary

Query parameters

productstring

Product whose usage to total.

Example:automations
categorystring nullable

Count one kind of work only, for example automation_run. More than one kind settles against the same balance, so a per-run average over all of them mixes runs with chat messages. Omit to total every category.

Example:automation_run
sincestring date-time nullable

Start of the window, inclusive. Omit to start at the account's first event. A value with no offset is read as UTC, which is what created_at in /history reports.

Example:2026-07-15T00:00:00Z
untilstring date-time nullable

End of the window, exclusive. Omit to run to now. A value with no offset is read as UTC.

Example:2026-08-15T00:00:00Z

Response

Successful Response

currencystring required

ISO currency code every amount in this response is in. Fixed for the life of the account: the first top-up pins the price, and the price fixes the currency.

usage_countinteger required

How many usage events settled in the window. One per unit of billable work: an automation run, or a chat message. Narrow it with category to count one kind. A run that failed before it reached the provider counts here and adds 0 to the amounts: it happened, and it cost nothing.

charged_unitsinteger required

Units those events took off the balance, as a positive number. The ledger unit, kept for support and reconciliation; display charged_amount instead. Covers settled usage only, so it is smaller than the sum of charged_units over the same window in /history, which also carries reversed grants.

charged_amountinteger required

charged_units in money, in microdollars (millionths of one currency unit), so 11287800 is $11.2878. Divide by usage_count for the per-run figure; guard the zero case, because an account with no usage reports 0 for both.

Example response

{
  "currency": "usd",
  "usage_count": 412,
  "charged_units": 5643900,
  "charged_amount": 11287800
}