--- title: "List spend limits" method: GET path: "/spend_limits" tags: ["Spend Limits"] --- # List spend limits `GET /spend_limits` ## Request - Base URL: `https://api.telnyx.com/v2` - URL: `https://api.telnyx.com/v2/spend_limits` - Auth: HTTP bearer Returns one entry per product and period you can set a limit on, with the limit, the spend so far in the period and whether the product is blocked. An entry without a limit is still listed (`limit: null`). When the spend cannot be read, the entry is returned with `spend_usd: null` and `spend_error` set. The list is not paginated. Each entry also lists the API key limits of its product and period in `credential_limits`, with each key's spend and block, and in `allocation` how much of the total limit they use. ## Response `200` Spend limits, spend and blocks per product and period. - SpendLimitListResponse - `data` SpendLimit[], required - `record_type` string, required: Identifies the type of the resource. - `product` string, required: Product the entry applies to. - `product_name` string, required: Display name of the product. - `period` 'daily' | 'monthly', required: `daily` is the current UTC day; `monthly` is the current UTC calendar month. - `period_start` string, date, required: First UTC day of the current period. - `period_end` string, date, required: Exclusive end of the current period, a UTC date. - `credential_id` string, nullable: In write responses, the API key the write was about; `null` for the total limit. Always `null` in list entries, which describe the total limit. - `limit` SpendLimitLimit, nullable, required: The limit set on the account for the product and period, whoever set it. `null` when none is set. - `amount` string, nullable, required: Limit in USD, as a decimal string. `null` when `unlimited` is true. - `unlimited` boolean, required: True when the limit was set to explicitly no cap. - `origin` 'self_service' | 'operator', required: `self_service` when a user of the account set it, `operator` when Telnyx support did. - `updated_at` string, date-time, required: When the limit was last set or changed. - `effective_limit_usd` string, nullable, required: The limit in USD that is enforced, as a decimal string. `null` means unlimited. - `spend_usd` string, nullable, required: Spend in USD so far in the period, as a decimal string. It can lag actual usage by about a minute. `null` when it could not be read. - `spend_error` string, nullable, required: Set when `spend_usd` is `null`. - `blocked` boolean, required: The product is blocked for the whole account in this period (total limit). An API key's own block appears only in `credential_limits`. Always `false` in write responses; list the limits to read the block state. - `block` SpendLimitBlock, nullable, required: The active block of the period. `null` when the period is not blocked. - `detected_at` string, date-time, required: When the block started. - `spend_usd` string, required: Spend in USD when the block started, as a decimal string. - `limit_usd` string, required: The limit in USD that the spend went above, as a decimal string. - `blocked_until` string, date, required: Exclusive end of the block: it is lifted at 00:00 UTC on this date at the latest. - `allocation` SpendLimitAllocation, nullable: How much of the period's total limit is given to API key limits. `null` unless the period has a total limit with an amount. - `total_limit_usd` string, required: The total limit in USD, as a decimal string. - `allocated_usd` string, required: Sum of the period's API key limits in USD, as a decimal string. - `unallocated_usd` string, required: The part of the total not given to API key limits, as a decimal string: the largest amount a new API key limit can have. - `over_allocated_usd` string, required: How far the API key limits exceed the total, as a decimal string. Non-zero only after Telnyx support lowered the total below them. - `credential_limits` SpendLimitCredentialLimit[]: List responses only. One item per API key limit of the product and period, sorted by `credential_id`, plus every API key that is still blocked. `[]` when there are none. - `credential_id` string, required: Identifier of the API key as recorded on usage. Never the key's secret. - `limit` SpendLimitCredentialLimitValue, nullable, required: The limit of one API key. It always has an amount. `null` for an API key that is still blocked after its limit was removed. - `amount` string, required: Limit in USD, as a decimal string. - `origin` 'self_service' | 'operator', required: `self_service` when a user of the account set it, `operator` when Telnyx support did. - `updated_at` string, date-time, required: When the limit was last set or changed. - `spend_usd` string, nullable, required: Spend in USD in the period made with exactly this API key, as a decimal string. Usage without an API key identifier, or with another one, counts only toward the total. `null` when it could not be read. - `spend_error` string, nullable, required: Set when `spend_usd` is `null`. - `blocked` boolean, required: This API key is blocked for the period. - `block` SpendLimitBlock, nullable, required: The active block of the period. `null` when the period is not blocked. - `detected_at` string, date-time, required: When the block started. - `spend_usd` string, required: Spend in USD when the block started, as a decimal string. - `limit_usd` string, required: The limit in USD that the spend went above, as a decimal string. - `blocked_until` string, date, required: Exclusive end of the block: it is lifted at 00:00 UTC on this date at the latest. - `evaluation` SpendLimitEvaluation: What a create, update or delete did to the period at once. Only present in write responses. - `spend_usd` string, nullable, required: Spend in USD used for the check, as a decimal string. `null` when the spend was not checked. - `released` boolean, required: The change lifted a block of this period. - `blocked_now` boolean, required: The change blocked the product: the spend was already above the new limit. - `still_over_limit` boolean, required: A block of this period remains because the spend is still above the new limit. - `still_blocked_other_period` boolean, required: The other period has an active block, so the product stays blocked whatever this period's result. For an API key write, the API key's limit in the other period. - `account_blocked` boolean: API key writes only: the account itself remains blocked for the product under a total limit. Absent for total limit writes. - `evaluation_deferred` boolean, required: The spend could not be checked now. The change is saved and applied within a few minutes. - `note` string: Additional information about the result, when there is any. - `meta` SpendLimitsPaginationMeta - `total_pages` integer - `total_results` integer - `page_number` integer - `page_size` integer ## Other responses - `401`: Unauthorized. The request did not carry valid Telnyx API credentials. - `403`: Forbidden. The caller's access policy does not allow this spend limits action. ## Changes - **2026-10-22** `4de6bba1c49d`: 4 info - added the optional property `data/items/allocation` to the response with the `200` status - added the optional property `data/items/credential_id` to the response with the `200` status - added the optional property `data/items/credential_limits` to the response with the `200` status - added the optional property `data/items/evaluation/account_blocked` to the response with the `200` status - **2026-10-15** `a72569d69430`: 1 info - endpoint added [Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/spend_limits/get.md) --- [API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)