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

# Usage Billing History

`GET /api/v1/usage_billing/history`

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

This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for
details on using cursor-based pagination.

## Query parameters

- `product` string — Product whose ledger to read.
- `cursor` string, nullable — An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request
- `limit` integer — The number of objects to return in a page

## Response `200`

Successful Response

- HistoryResponse
  - `currency` string, 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.
  - `entries` HistoryEntry[], required — Ledger entries in the current page, newest first.
    - `id` integer, required — Ledger entry id.
    - `type` string, required — What moved the balance: `usage_settled`, `top_up`, `void`, `expiry` or `chargeback`.
    - `created_at` string, required — When the entry was written, UTC.
    - `category` string — What produced the entry, within its `type`: `automation_run`, `paid`, `promotional` or `stripe`.
    - `status` string — Outcome of the run this entry settles: `success`, `failed`, `cancelled`, `timed_out` or `partial`. Present on `usage_settled` only. It does not change the amount: every terminal outcome draws the cost the run actually incurred.
    - `charged_units` integer, nullable, required — Units taken off the balance, as a positive number, or `null` on a credit, which has no debit side. `0` is a real value and not an absent one: a run that failed before it reached the provider cost nothing. Not a usage figure on its own: `void`, `expiry` and `chargeback` are debits too, so summing this field across types overstates usage by every reversed grant. Filter on `type` to total usage.
    - `charged_amount` integer, nullable, required — `charged_units` in money, in microdollars (millionths of one page-level `currency` unit), so 27400 is $0.0274. `null` exactly when `charged_units` is.
    - `credited_units` integer, nullable, required — Units added to the balance, as a positive number, or `null` on a debit. Set on credits (`top_up`).
    - `credited_amount` integer, nullable, required — `credited_units` in money, in microdollars (millionths of one page-level `currency` unit), so 10000000 is $10.00. `null` exactly when `credited_units` is.
    - `refs` object — Free-form attribution for the entry. Contents vary by `type` and are not part of the API contract.
    - `description` string — Human-readable summary of the entry.
  - `has_more` boolean, required — Whether another page of results is available.
  - `next_cursor` string — Cursor for the next page of results.

## 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)