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

# List spend limits

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



## OpenAPI

````yaml /openapi/source/external/billing/spend-limits.json get /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:
    get:
      tags:
        - Spend Limits
      summary: List spend limits
      description: >-
        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.
      operationId: listSpendLimits
      responses:
        '200':
          description: Spend limits, spend and blocks per product and period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendLimitListResponse'
              examples:
                daily_limit_set:
                  summary: A daily limit and no monthly 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
                      - record_type: spend_limit
                        product: inference
                        product_name: Inference
                        period: monthly
                        period_start: '2026-09-01'
                        period_end: '2026-10-01'
                        limit: null
                        effective_limit_usd: null
                        spend_usd: '812.03'
                        spend_error: null
                        blocked: false
                        block: null
                    meta:
                      total_pages: 1
                      total_results: 2
                      page_number: 1
                      page_size: 2
                blocked:
                  summary: Blocked by the daily 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: '10'
                          unlimited: false
                          origin: self_service
                          updated_at: '2026-09-24T08:00:00Z'
                        effective_limit_usd: '10'
                        spend_usd: '12.80'
                        spend_error: null
                        blocked: true
                        block:
                          detected_at: '2026-09-24T08:41:17Z'
                          spend_usd: '10.20'
                          limit_usd: '10'
                          blocked_until: '2026-09-25'
                      - record_type: spend_limit
                        product: inference
                        product_name: Inference
                        period: monthly
                        period_start: '2026-09-01'
                        period_end: '2026-10-01'
                        limit: null
                        effective_limit_usd: null
                        spend_usd: '812.03'
                        spend_error: null
                        blocked: false
                        block: null
                    meta:
                      total_pages: 1
                      total_results: 2
                      page_number: 1
                      page_size: 2
        '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.
      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
            });

            // Automatically fetches more pages as needed.
            for await (const response of client.spendLimits.list()) {
              console.log(response);
            }
        - 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
            )
            page = client.spend_limits.list()
            print(page.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\tspendLimits, err := client.SpendLimits.List(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", spendLimits.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

            import com.telnyx.sdk.client.TelnyxClient;
            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

            public final class Main {
                private Main() {}

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

                    var page = client.spendLimits().list();
                }
            }
        - lang: Ruby
          source: |-
            require "telnyx"

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

            page = telnyx.spend_limits.list

            puts(page)
        - 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 {
              $page = $client->spendLimits->list();

              var_dump($page);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx spend-limits list \
              --api-key 'My API Key'
components:
  schemas:
    SpendLimitListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SpendLimit'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      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
    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
    PaginationMeta:
      type: object
      properties:
        total_pages:
          type: integer
          example: 1
        total_results:
          type: integer
          example: 2
        page_number:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 2
    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

````