> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a spend limit

> 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.



## OpenAPI

````yaml /openapi/source/external/billing/spend-limits.json post /spend_limits
openapi: 3.0.0
info:
  version: 1.0.0
  title: Spend Limits API
  description: >-
    Cap how much your account spends on a product per day and per month, in USD.
    When the spend in a period goes above the limit, the product is blocked for
    your account until the period ends.
  contact:
    email: support@telnyx.com
servers:
  - url: https://api.telnyx.com/v2
    description: Version 2.0.0 of the Telnyx API
security:
  - bearerAuth: []
tags:
  - name: Spend Limits
    description: >-
      Daily and monthly spend limits per product. A limit applies to the
      organization of the authenticated user, or to the user's own account when
      they belong to no organization; every user of the organization sees and
      changes the same limits.


      - **Periods.** `daily` covers the current UTC day and `monthly` the
      current UTC calendar month. The two limits are independent: you can set
      either, both or neither.

      - **Blocking.** When spend in a period goes above the limit (strictly
      greater), the product is blocked until the period ends: 00:00 UTC the next
      day for `daily`, 00:00 UTC on the 1st of the next month for `monthly`. A
      block appears within about 2 minutes (daily) or 10 minutes (monthly) of
      the spend being recorded.

      - **Changes apply immediately.** Creating, updating or deleting a limit
      checks the period's spend in the same request: raising the limit above the
      spend, or removing it, lifts that period's block, and lowering it below
      the spend blocks the product at once. The `evaluation` object in the
      response says what happened.

      - **Supported products.** Today only `inference` supports spend limits. A
      blocked account gets HTTP 403 with the error title `Inference spend limit
      reached` (code `10039`) on new billable chat completions, Responses,
      Anthropic Messages and classification requests; requests already running
      finish normally. Take the list of products from the list operation.

      - **Limits set by Telnyx.** Telnyx support can also set a limit on your
      account. It is listed with `origin: operator` and you can update or delete
      it like your own.
paths:
  /spend_limits:
    post:
      tags:
        - Spend Limits
      summary: Create a spend limit
      description: >-
        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.
      operationId: createSpendLimit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpendLimitRequest'
            examples:
              amount:
                summary: A daily limit of 100 USD
                value:
                  product: inference
                  period: daily
                  amount: 100
                  reason: Team budget
              unlimited:
                summary: Explicitly no monthly limit
                value:
                  product: inference
                  period: monthly
                  unlimited: true
      responses:
        '200':
          description: >-
            The limit was created. `evaluation` says whether the change blocked
            the product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendLimitResponse'
              examples:
                created:
                  summary: Created, spend below the limit
                  value:
                    data:
                      record_type: spend_limit
                      product: inference
                      product_name: Inference
                      period: daily
                      period_start: '2026-09-24'
                      period_end: '2026-09-25'
                      limit:
                        amount: '100'
                        unlimited: false
                        origin: self_service
                        updated_at: '2026-09-24T09:12:03.412Z'
                      effective_limit_usd: '100'
                      spend_usd: '37.41'
                      spend_error: null
                      blocked: false
                      block: null
                      evaluation:
                        spend_usd: '37.41'
                        released: false
                        blocked_now: false
                        still_over_limit: false
                        still_blocked_other_period: false
                        evaluation_deferred: false
                blocked_now:
                  summary: 'Created below the current spend: blocked at once'
                  value:
                    data:
                      record_type: spend_limit
                      product: inference
                      product_name: Inference
                      period: daily
                      period_start: '2026-09-24'
                      period_end: '2026-09-25'
                      limit:
                        amount: '20'
                        unlimited: false
                        origin: self_service
                        updated_at: '2026-09-24T09:12:03.412Z'
                      effective_limit_usd: '20'
                      spend_usd: '37.41'
                      spend_error: null
                      blocked: false
                      block: null
                      evaluation:
                        spend_usd: '37.41'
                        released: false
                        blocked_now: true
                        still_over_limit: false
                        still_blocked_other_period: false
                        evaluation_deferred: false
        '400':
          description: >-
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported_product:
                  summary: Product without self-service spend limits
                  value:
                    errors:
                      - code: '10015'
                        title: Product does not support self-service spend limits
                        detail: >-
                          Spend limits for this product cannot be managed
                          through the API; contact support
                invalid_period:
                  summary: Invalid period
                  value:
                    errors:
                      - code: '10015'
                        title: Invalid period
                        detail: period must be daily or monthly
                invalid_limit:
                  summary: Invalid amount or unlimited
                  value:
                    errors:
                      - code: '10015'
                        title: Invalid override
                        detail: >-
                          Exactly one of amount (>= 0) or unlimited: true must
                          be given
                period_not_available:
                  summary: Product and period cannot be limited
                  value:
                    errors:
                      - code: '10015'
                        title: Spend limits are not available
                        detail: Spend limits are not available for inference (monthly)
                reason_too_long:
                  summary: Reason too long
                  value:
                    errors:
                      - code: '10015'
                        title: Invalid reason
                        detail: reason must be at most 500 characters
                unknown_field:
                  summary: Unknown field in the body
                  value:
                    errors:
                      - code: '10015'
                        title: Unknown fields
                        detail: >-
                          Unknown field(s): user_id; the account is always the
                          one you are authenticated as
        '401':
          description: >-
            Unauthorized. The request did not carry valid Telnyx API
            credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Missing or invalid credentials
                  value:
                    errors:
                      - code: '10009'
                        title: Authentication failed
                        detail: >-
                          The required authentication headers were either
                          invalid or not included in the request.
        '403':
          description: >-
            Forbidden. The caller's access policy does not allow this spend
            limits action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Action not allowed
                  value:
                    errors:
                      - code: '10010'
                        title: Authorization failed
                        detail: >-
                          You do not have permission to perform the requested
                          action on the specified resource or resources.
        '409':
          description: Conflict. A limit already exists for the product and period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                limit_exists:
                  summary: Limit already exists
                  value:
                    errors:
                      - code: '10015'
                        title: Limit already exists
                        detail: >-
                          An active daily limit exists for inference; update it
                          instead
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Telnyx from 'telnyx';

            const client = new Telnyx({
              apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
            });

            const SpendLimit = await client.spendLimits.create();

            console.log(SpendLimit.data);
        - lang: Python
          source: |
            import os
            from telnyx import Telnyx

            client = Telnyx(
                api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
            )
            spend_limit = client.spend_limits.create()
            print(spend_limit.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tspendLimit, err := client.SpendLimits.New(\n\t\tcontext.TODO(),\n\t\ttelnyx.SpendLimitNewParams{\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", spendLimit.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

            import com.telnyx.sdk.client.TelnyxClient;
            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
            import com.telnyx.sdk.models.spendLimits.SpendLimitCreateParams;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    TelnyxClient client = TelnyxOkHttpClient.fromEnv();

                    SpendLimitCreateParams params = SpendLimitCreateParams.builder()
                        .build();
                    var response = client.spendLimits().create(params);
                }
            }
        - lang: Ruby
          source: |-
            require "telnyx"

            telnyx = Telnyx::Client.new(api_key: "My API Key")

            spend_limit = telnyx.spend_limits.create

            puts(spend_limit)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Telnyx\Client;

            use Telnyx\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API
            Key');


            try {
              $spend_limit = $client->spendLimits->create();

              var_dump($spend_limit);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx spend-limits create \
              --api-key 'My API Key'
components:
  schemas:
    CreateSpendLimitRequest:
      description: 'Send exactly one of `amount` and `unlimited: true`.'
      oneOf:
        - $ref: '#/components/schemas/CreateSpendLimitWithAmount'
        - $ref: '#/components/schemas/CreateSpendLimitUnlimited'
    SpendLimitResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SpendLimit'
      required:
        - data
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - code
              - title
            properties:
              code:
                type: string
              title:
                type: string
              detail:
                type: string
              meta:
                type: object
                properties:
                  url:
                    type: string
              source:
                type: object
                properties:
                  pointer:
                    type: string
      required:
        - errors
    CreateSpendLimitWithAmount:
      title: Amount
      description: A limit in USD.
      type: object
      additionalProperties: false
      properties:
        product:
          type: string
          description: Product to limit, as returned in `product` by the list operation.
          example: inference
        period:
          $ref: '#/components/schemas/SpendLimitPeriod'
        amount:
          type: number
          minimum: 0
          description: Limit in USD. `0` blocks at the first cent of spend.
          example: 100
        unlimited:
          type: boolean
          enum:
            - false
          description: Optional; only `false` is allowed together with `amount`.
          example: false
        reason:
          type: string
          maxLength: 500
          description: Why the limit is set or changed, kept for audit.
          example: Team budget
      required:
        - product
        - amount
    CreateSpendLimitUnlimited:
      title: Unlimited
      description: Explicitly no cap.
      type: object
      additionalProperties: false
      properties:
        product:
          type: string
          description: Product to limit, as returned in `product` by the list operation.
          example: inference
        period:
          $ref: '#/components/schemas/SpendLimitPeriod'
        unlimited:
          type: boolean
          enum:
            - true
          description: '`true`: explicitly no cap.'
          example: true
        reason:
          type: string
          maxLength: 500
          description: Why the limit is set or changed, kept for audit.
          example: Team budget
      required:
        - product
        - unlimited
    SpendLimit:
      type: object
      description: The spend limit, spend and block state of one product and period.
      properties:
        record_type:
          type: string
          description: Identifies the type of the resource.
          example: spend_limit
        product:
          type: string
          description: Product the entry applies to.
          example: inference
        product_name:
          type: string
          description: Display name of the product.
          example: Inference
        period:
          $ref: '#/components/schemas/SpendLimitPeriod'
        period_start:
          type: string
          format: date
          description: First UTC day of the current period.
          example: '2026-09-24'
        period_end:
          type: string
          format: date
          description: Exclusive end of the current period, a UTC date.
          example: '2026-09-25'
        limit:
          $ref: '#/components/schemas/SpendLimitLimit'
        effective_limit_usd:
          type: string
          nullable: true
          description: >-
            The limit in USD that is enforced, as a decimal string. `null` means
            unlimited.
          example: '100'
        spend_usd:
          type: string
          nullable: true
          description: >-
            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.
          example: '37.41'
        spend_error:
          type: string
          nullable: true
          description: Set when `spend_usd` is `null`.
          example: null
        blocked:
          type: boolean
          description: >-
            The product is blocked for this period. Always `false` in write
            responses; list the limits to read the block state.
          example: false
        block:
          $ref: '#/components/schemas/SpendLimitBlock'
        evaluation:
          $ref: '#/components/schemas/SpendLimitEvaluation'
      required:
        - record_type
        - product
        - product_name
        - period
        - period_start
        - period_end
        - limit
        - effective_limit_usd
        - spend_usd
        - spend_error
        - blocked
        - block
    SpendLimitPeriod:
      type: string
      description: >-
        `daily` is the current UTC day; `monthly` is the current UTC calendar
        month.
      enum:
        - daily
        - monthly
      default: daily
      example: daily
    SpendLimitLimit:
      type: object
      nullable: true
      description: >-
        The limit set on the account for the product and period, whoever set it.
        `null` when none is set.
      properties:
        amount:
          type: string
          nullable: true
          description: Limit in USD, as a decimal string. `null` when `unlimited` is true.
          example: '100'
        unlimited:
          type: boolean
          description: True when the limit was set to explicitly no cap.
          example: false
        origin:
          type: string
          enum:
            - self_service
            - operator
          description: >-
            `self_service` when a user of the account set it, `operator` when
            Telnyx support did.
          example: self_service
        updated_at:
          type: string
          format: date-time
          description: When the limit was last set or changed.
          example: '2026-09-24T09:12:03.412Z'
      required:
        - amount
        - unlimited
        - origin
        - updated_at
    SpendLimitBlock:
      type: object
      nullable: true
      description: The active block of the period. `null` when the period is not blocked.
      properties:
        detected_at:
          type: string
          format: date-time
          description: When the block started.
          example: '2026-09-24T08:41:17Z'
        spend_usd:
          type: string
          description: Spend in USD when the block started, as a decimal string.
          example: '10.20'
        limit_usd:
          type: string
          description: The limit in USD that the spend went above, as a decimal string.
          example: '10'
        blocked_until:
          type: string
          format: date
          description: >-
            Exclusive end of the block: it is lifted at 00:00 UTC on this date
            at the latest.
          example: '2026-09-25'
      required:
        - detected_at
        - spend_usd
        - limit_usd
        - blocked_until
    SpendLimitEvaluation:
      type: object
      description: >-
        What a create, update or delete did to the period at once. Only present
        in write responses.
      properties:
        spend_usd:
          type: string
          nullable: true
          description: >-
            Spend in USD used for the check, as a decimal string. `null` when
            the spend was not checked.
          example: '37.41'
        released:
          type: boolean
          description: The change lifted a block of this period.
          example: false
        blocked_now:
          type: boolean
          description: >-
            The change blocked the product: the spend was already above the new
            limit.
          example: false
        still_over_limit:
          type: boolean
          description: >-
            A block of this period remains because the spend is still above the
            new limit.
          example: false
        still_blocked_other_period:
          type: boolean
          description: >-
            The other period has an active block, so the product stays blocked
            whatever this period's result.
          example: false
        evaluation_deferred:
          type: boolean
          description: >-
            The spend could not be checked now. The change is saved and applied
            within a few minutes.
          example: false
        note:
          type: string
          description: Additional information about the result, when there is any.
          example: >-
            A block was lifted by Telnyx support today; this limit applies from
            tomorrow.
      required:
        - spend_usd
        - released
        - blocked_now
        - still_over_limit
        - still_blocked_other_period
        - evaluation_deferred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````