---
title: "Create a spend limit"
method: POST
path: "/spend_limits"
tags: ["Spend Limits"]
---

# Create a spend limit

`POST /spend_limits`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/spend_limits`
- Auth: HTTP bearer

Sets a limit for a product and period that has none. Send exactly one of `amount` and `unlimited: true`. The period's spend is checked at once: if it is already above the new limit, the product is blocked immediately (`evaluation.blocked_now`). Returns 409 when a limit already exists for the product and period; update it instead. With `credential_id`, the limit applies to that API key only: it needs an `amount`, and the period's API key limits cannot add up to more than the total limit when the total has an amount.

## Request body

- union: Send exactly one of `amount` and `unlimited: true`.
  - CreateSpendLimitWithAmount: A limit in USD.
    - `product` string, required: Product to limit, as returned in `product` by the list operation.
    - `period` 'daily' | 'monthly': `daily` is the current UTC day; `monthly` is the current UTC calendar month.
    - `credential_id` string, nullable: Optional. Identifier of one API key as recorded on usage, never the key's secret: the limit then applies to that key only. Absent or `null` sets the total limit. A blank value, or one with control characters, is refused; it never means the total limit. An API key limit always has an `amount`.
    - `amount` number, required: Limit in USD. `0` blocks at the first cent of spend.
    - `unlimited` false: Optional; only `false` is allowed together with `amount`.
    - `reason` string: Why the limit is set or changed, kept for audit.
  - CreateSpendLimitUnlimited: Explicitly no cap. Not available for API key limits.
    - `product` string, required: Product to limit, as returned in `product` by the list operation.
    - `period` 'daily' | 'monthly': `daily` is the current UTC day; `monthly` is the current UTC calendar month.
    - `unlimited` true, required: `true`: explicitly no cap.
    - `reason` string: Why the limit is set or changed, kept for audit.

## Response `200`

The limit was created. `evaluation` says whether the change blocked the product.

- SpendLimitResponse
  - `data` SpendLimit, required: The spend limit, spend and block state of one product and period. The top-level fields describe the total limit of the account; API key limits are nested in `credential_limits`.
    - `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.

## Other responses

- `400`: Bad request. The product does not support self-service spend limits, the period is invalid or not available, not exactly one of `amount` and `unlimited` was sent, `amount` is negative, `reason` is longer than 500 characters, or the body has a field that is not listed. For an API key limit (`credential_id`): API key limits are not available for the product or period, `credential_id` is invalid, `unlimited` was sent, the period already has the maximum number of API key limits, or the period's API key limits would add up to more than the total limit. Creating a total limit below the sum of the period's API key limits is refused too.
- `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.
- `409`: Conflict. A limit already exists for the product and period, or for the API key.

## Changes

- **2026-10-22** `4de6bba1c49d`: 5 info
  - added the new optional request property `oneOf[subschema #1: Amount]/credential_id`
  - added the optional property `data/allocation` to the response with the `200` status
  - added the optional property `data/credential_id` to the response with the `200` status
  - added the optional property `data/credential_limits` to the response with the `200` status
  - …1 more
- **2026-10-15** `a72569d69430`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/spend_limits/post.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)