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

# Usage Billing State

`GET /api/v1/usage_billing/state`

Read the caller's usage-billing credit state for a product.

## Query parameters

- `product` string — Product whose credit state to read.

## Response `200`

Successful Response

- CreditStateResponse
  - `available_units` integer, required — Balance net of in-flight holds (`available_cached - held`). The ledger unit, kept for support and reconciliation; display `available_amount` instead. Not a permission to start a run: use `usage_allowed` for that.
  - `available_amount` integer, required — `available_units` in money, in microdollars (millionths of one `currency` unit), so 8372600 is $8.3726. The scale is exact for every amount this API reports; cents and hundredths of a cent both truncate a single chat message to zero. Converted by the server because the client cannot: the ratio is the account's pinned price and only the backend holds it.
  - `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_allowed` boolean, required — Whether a new run may start right now.
  - `low_balance` boolean, required — Balance is at or below the low-balance threshold.
  - `depleted` boolean, required — No further runs may start. Equivalent to `usage_allowed` being false; can be true while `available_units` is still positive, because the floor holds back one run's worth.

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