TOtodoist
Billing

Usage Billing History

Changed on

List the caller's usage-billing ledger entries, newest first.

Use types to filter the entries to list. A user who has never topped up gets an empty page.

This is a paginated endpoint. See the Pagination guide for details on using cursor-based pagination.

get/api/v1/usage_billing/history

Request

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

Query parameters

productstring

Product whose ledger to read.

Example:automations
typesstring nullable

Comma-separated type values to return: usage_settled, top_up, adjustment, void, expiry, or chargeback. When omitted, all types are returned. Rejects when an unrecognized name is supplied.

Example:top_up
cursorstring nullable

An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request

Example:14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55
limitinteger

The number of objects to return in a page

Example:50

Response

Successful Response

currencystring required

ISO currency code every amount in this page is in. On the page rather than on each entry: the account pins one price for its whole life (spec section 8), so no two entries can differ.

has_moreboolean required

Whether another page of results is available.

next_cursorstring

Cursor for the next page of results.

Example response

{
  "currency": "usd",
  "entries": [
    {
      "id": 8814,
      "type": "usage_settled",
      "created_at": "2026-06-10T14:00:00Z",
      "category": "automation_run",
      "status": "success",
      "charged_units": 13700,
      "charged_amount": 27400,
      "credited_units": 5000000,
      "credited_amount": 10000000,
      "description": "Top-up USD 1000"
    }
  ],
  "next_cursor": "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55"
}

Changes

  • bbc2262e73bbRevision changes
    • info

      added the new optional query request parameter types

  • 16439be15248Revision changes
    • breaking

      response property entries/items/charged_units list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property entries/items/credited_units list-of-types was widened by adding types null to media type application/json of response 200

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      added the required property to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status