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

# Get your team's daily cap and overage budget

> Returns your Business team's daily cap (tool calls a UTC day, after which new runs are refused) and overage budget (the overage it expects each billing period, for budget alerts), each with whether it is on and who changed it last.

> [accordion] Details
>
> At the cap, new runs are refused with quota\_exceeded until the UTC day resets, and runs already started finish.
>
> * The cap keeps what it was set in, its basis: calls, or overage dollars. effective\_calls is what it comes to today; a cap in dollars counts at each UTC day's included calls and overage price, so it stays the same dollars when they change.
>
> * Every member reads the basis and the calls. overage\_cents and overage\_budget, in dollars, are for Owners and Admins only, and for an API key only with team:manage.
>
> * **Callers:** an API key, an MCP OAuth token or a Dashboard session.
>
> * **Permission:** `usage:read`.
>
> * **Effect:** Changes nothing.
>
> * **Errors:** [`business_account_required`](https://docs.pomerado.ai/errors#business_account_required), and the [errors any request can get](https://docs.pomerado.ai/errors.md).


## OpenAPI

````yaml /api-reference/openapi.json get /v1/usage/spend-controls
openapi: 3.1.0
info:
  title: Pomerado API
  version: '1'
  description: >-
    Run and build website tools, follow their jobs, and manage logins, API keys
    and webhooks. Authenticate with a Pomerado API key (pom_…), an MCP OAuth
    token or a Dashboard session as a Bearer token.
servers:
  - url: https://api.pomerado.ai
security: []
tags:
  - name: account
    x-group: Account
  - name: api_keys
    x-group: API keys
  - name: connected_apps
    x-group: Connected apps
  - name: usage
    x-group: Usage
  - name: quota
    x-group: Quota
  - name: spend_controls
    x-group: Spend controls
  - name: usage_alerts
    x-group: Usage alerts
  - name: usage_summary
    x-group: Usage summary
  - name: billing
    x-group: Billing
  - name: integrations
    x-group: Integrations
  - name: connect
    x-group: Connect
  - name: code
    x-group: Code
  - name: logins
    x-group: Saved logins
  - name: two_factor
    x-group: 2FA
  - name: login_access
    x-group: Login access
  - name: tools
    x-group: Tools
  - name: shapes
    x-group: Shapes
  - name: webhooks
    x-group: Webhooks
  - name: payer_profiles
    x-group: Payer profiles
  - name: payer_addresses
    x-group: Payer addresses
  - name: payment_methods
    x-group: Payment methods
  - name: runs
    x-group: Runs
  - name: builds
    x-group: Builds
  - name: jobs
    x-group: Jobs
  - name: suggestions
    x-group: Suggestions
  - name: audit
    x-group: Audit
  - name: files
    x-group: Files
  - name: team
    x-group: Team
  - name: sso
    x-group: Single sign-on
  - name: issue_reports
    x-group: Problem reports
paths:
  /v1/usage/spend-controls:
    get:
      tags:
        - spend_controls
      summary: Get your team's daily cap and overage budget
      description: >-
        Returns your Business team's daily cap (tool calls a UTC day, after
        which new runs are refused) and overage budget (the overage it expects
        each billing period, for budget alerts), each with whether it is on and
        who changed it last.
      operationId: spend_controls.get
      responses:
        '200':
          description: Your team's spend controls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendControls'
        '400':
          description: invalid_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: unauthorized, reauthentication_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: business_account_required, forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: temporarily_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearer: []
components:
  schemas:
    SpendControls:
      type: object
      required:
        - daily_cap
      properties:
        daily_cap:
          type: object
          required:
            - 'on'
            - basis
            - calls
            - effective_calls
            - changed_by
            - changed_at
          properties:
            'on':
              type: boolean
            basis:
              anyOf:
                - type: string
                  enum:
                    - calls
                    - overage_cents
                - type: 'null'
              description: >-
                What the cap was set in: calls, or overage_cents (overage
                dollars). Null until first set
            calls:
              anyOf:
                - type: integer
                  description: a non-negative number
                  minimum: 0
                - type: 'null'
              description: The calls a UTC day it was set to; null unless basis is calls
            overage_cents:
              anyOf:
                - type: integer
                  description: a non-negative number
                  minimum: 0
                - type: 'null'
              description: >-
                Owners and Admins only. The overage dollars a UTC day it was set
                to, in US cents; null unless basis is overage_cents. They stay
                the same dollars when the price or the included calls change
            effective_calls:
              anyOf:
                - type: integer
                  description: a non-negative number
                  minimum: 0
                - type: 'null'
              description: >-
                Tool calls today, the UTC day, the cap stands at; only runs
                count, never builds. While the cap is on, new runs past it are
                refused with quota_exceeded (details.limit_source team_cap)
                until the UTC day resets; runs already started finish. A cap in
                dollars comes to today's included calls plus its dollars over
                today's overage price, rounded down, so it follows the terms
                each day. Null until first set, and for a cap in dollars while
                the team has no billing terms or free overage, when it refuses
                no runs
            changed_by:
              anyOf:
                - $ref: '#/components/schemas/SpendControlPerson'
                - type: 'null'
              description: Who changed it last; null until first set
            changed_at:
              anyOf:
                - type: string
                  description: ISO 8601 UTC
                - type: 'null'
              description: When it was last changed; null until first set
          additionalProperties: false
          description: Kept while off
        overage_budget:
          type: object
          required:
            - 'on'
            - cents
            - changed_by
            - changed_at
          properties:
            'on':
              type: boolean
            cents:
              anyOf:
                - type: integer
                  description: a non-negative number
                  minimum: 0
                - type: 'null'
              description: >-
                Expected overage each billing period, in US cents, which budget
                alerts measure against. It never stops runs. Null until first
                set
            changed_by:
              anyOf:
                - $ref: '#/components/schemas/SpendControlPerson'
                - type: 'null'
              description: Who changed it last; null until first set
            changed_at:
              anyOf:
                - type: string
                  description: ISO 8601 UTC
                - type: 'null'
              description: When it was last changed; null until first set
          additionalProperties: false
          description: Owners and Admins only. Kept while off
        today:
          type: object
          required:
            - refused_runs
            - first_refused_at
          properties:
            refused_runs:
              type: integer
              description: >-
                New runs refused today, the UTC day, for being over the day's
                tool call limit: the cap while on, or a limit Pomerado set,
                whichever is lower. Each request counts once, however often it
                was retried with its idempotency key
              minimum: 0
            first_refused_at:
              anyOf:
                - type: string
                  description: ISO 8601 UTC
                - type: 'null'
              description: When the first of them was refused; null when none was
            limit_source:
              anyOf:
                - type: string
                  enum:
                    - team_cap
                    - pomerado
                - type: 'null'
              description: >-
                Which limit holds today: team_cap, the team's own cap, lower
                than any limit Pomerado set; pomerado, a limit Pomerado set,
                lower than the cap or equal to it, or with the cap off; null
                when neither limits the day. Absent while it can't be read
          additionalProperties: false
          description: Absent while they can't be counted
      additionalProperties: false
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - retryable
            - docs_url
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            docs_url:
              type: string
            details:
              type: object
              required: []
              properties: {}
              additionalProperties:
                $id: /schemas/unknown
          additionalProperties: false
      additionalProperties: false
    SpendControlPerson:
      type: object
      required:
        - member_id
        - name
        - email
      properties:
        member_id:
          type: string
          description: The member's user ID
        name:
          anyOf:
            - type: string
            - type: 'null'
        email:
          anyOf:
            - type: string
            - type: 'null'
      additionalProperties: false
      description: >-
        A member. name and email are null once your team no longer knows them,
        and to an API key without team:manage for anyone but its own member
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.