---
title: "Usage Billing Usage Summary"
method: GET
path: "/api/v1/usage_billing/usage_summary"
tags: ["Billing"]
---

# Usage Billing Usage Summary

`GET /api/v1/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.

## Query parameters

- `product` string — Product whose usage to total.
- `category` string, 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.
- `since` string, 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.
- `until` string, date-time, nullable — End of the window, exclusive. Omit to run to now. A value with no offset is read as UTC.

## Response `200`

Successful Response

- UsageSummaryResponse
  - `currency` string, 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_count` integer, 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_units` integer, 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_amount` integer, 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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

---

[API](https://skmtc.net/todoist/apis/todoist-api.md) · [All operations](https://skmtc.net/todoist/apis/todoist-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/todoist/todoist-api/revisions/69a962f1578f/schema)