TOtodoist
Billing

Usage Billing Usage Summary

Changed on

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.

A user who has never topped up reports zero for every field.

group_by=automation adds groups: the same total, one entry per automation. Older usage without an automation id groups by its label.

get/api/v1/usage_billing/usage_summary

Request

  • Base URL
    https://api.todoist.com
  • URL
    https://api.todoist.com/api/v1/usage_billing/usage_summary
  • Auth
    none declared

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
group_by'automation' nullable

Split the total by the automation that ran, in groups. Send category=automation_run with it: chat messages carry no automation, so without the filter each chat label becomes a group of its own.

Example:automation

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. A user who has not topped up yet reads the currency they will be charged in.

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,
  "groups": [
    {
      "automation_id": "0199a3c4-5b6e-7f80-9a1b-2c3d4e5f6a7b",
      "charged_amount": 1148000,
      "charged_units": 574000,
      "description": "Automation: Daily digest",
      "usage_count": 42
    },
    {
      "charged_amount": 82200,
      "charged_units": 41100,
      "description": "Automation: Triage",
      "usage_count": 3
    }
  ]
}

Changes