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

# Evaluate a budget's spend now

> Measures the budget against the warehouse now and stores the result, rather than waiting for the daily refresh, then returns the summary it wrote. The one budget operation that runs a warehouse query, so it is slower than a read and costs warehouse time — call it when a budget has just been created or changed, not to poll. Returns `409` if the budget changed while it was being measured. Requires `budgets:write`.



## OpenAPI

````yaml https://api.select.dev/v2/openapi.json post /budgets/{budget_id}/actions/evaluate
openapi: 3.1.0
info:
  title: SELECT API (v2)
  version: 0.1.0
servers:
  - url: https://api.select.dev/v2
    description: SELECT API v2
security: []
paths:
  /budgets/{budget_id}/actions/evaluate:
    post:
      tags:
        - budgets
      summary: Evaluate a budget's spend now
      description: >-
        Measures the budget against the warehouse now and stores the result,
        rather than waiting for the daily refresh, then returns the summary it
        wrote. The one budget operation that runs a warehouse query, so it is
        slower than a read and costs warehouse time — call it when a budget has
        just been created or changed, not to poll. Returns `409` if the budget
        changed while it was being measured. Requires `budgets:write`.
      operationId: evaluate_budget_route_budgets__budget_id__actions_evaluate_post
      parameters:
        - name: budget_id
          in: path
          required: true
          schema:
            type: string
            title: Budget Id
        - name: x-tenant-id
          in: header
          required: true
          schema:
            type: string
            description: The organization ID the request is scoped to.
            title: X-Tenant-Id
          description: The organization ID the request is scoped to.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetSpendSummaryV2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - HTTPBearer: []
components:
  schemas:
    BudgetSpendSummaryV2:
      properties:
        budget_id:
          type: string
          title: Budget Id
          description: The budget this summary is for.
          readOnly: true
          x-terraform-computed: true
        spend:
          anyOf:
            - type: number
            - type: 'null'
          title: Spend
          description: >-
            Spend so far in the current period, counting only days that have
            finished loading. Null before the budget's first refresh.
          readOnly: true
          x-terraform-computed: true
        forecast:
          anyOf:
            - type: number
            - type: 'null'
          title: Forecast
          description: >-
            Projected total spend by the end of the current period, extrapolated
            from the budget's recent daily spend. Null before the first refresh,
            when there is too little history to project from, or once the period
            has ended.
          readOnly: true
          x-terraform-computed: true
        forecast_diff:
          anyOf:
            - type: number
            - type: 'null'
          title: Forecast Diff
          description: >-
            How far `forecast` lands from the budget's threshold, as a
            percentage of it — positive over, negative under. Null when there is
            no forecast, or the threshold is zero.
          readOnly: true
          x-terraform-computed: true
        period_start:
          type: string
          format: date
          title: Period Start
          description: The first day of the period these figures cover.
          readOnly: true
          x-terraform-computed: true
        period_end:
          type: string
          format: date
          title: Period End
          description: The last day of the period these figures cover.
          readOnly: true
          x-terraform-computed: true
      type: object
      required:
        - budget_id
        - period_start
        - period_end
      title: BudgetSpendSummary
      description: >-
        What a budget has spent so far this period, and where it is heading.


        Refreshed once a day, on the same cadence as the budget's `status`. Only
        days

        that have finished loading count toward `spend`, and a day only finishes
        once,

        so these figures step forward daily rather than continuously. Null until
        the

        first refresh after the budget is created — evaluate the budget to fill
        them in

        without waiting for the next one.
    ProblemDetail:
      additionalProperties: true
      description: >-
        RFC 9457-style error payload, served as ``application/problem+json``.


        ``code`` is the stable, machine-readable identifier — consumers branch
        on it,

        never on ``title``. ``type`` stays ``about:blank``: we keep no per-error

        documentation pages. There is no ``instance``/request-id member (we
        don't run

        access logs). See the flat error-code catalogue in §4 of the standards
        doc.
      properties:
        type:
          default: about:blank
          title: Type
          type: string
        title:
          type: string
          title: Title
        status:
          title: Status
          type: integer
        detail:
          title: Detail
          type: string
        code:
          title: Code
          type: string
        retryable:
          title: Retryable
          type: boolean
        details:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          default: null
          title: Details
      required:
        - title
        - status
        - detail
        - code
        - retryable
      title: ProblemDetail
      type: object
  responses:
    BadRequest:
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        WWW-Authenticate:
          description: Authentication challenge for the requested resource.
          required: true
          schema:
            type: string
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    MethodNotAllowed:
      description: Method not allowed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Allow:
          description: HTTP methods supported by the requested resource.
          required: true
          schema:
            type: string
    RequestTimeout:
      description: Request Timeout
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Conflict:
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ValidationFailed:
      description: Validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    RateLimited:
      description: Rate limited
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          required: true
          schema:
            type: integer
            minimum: 0
    InternalError:
      description: Internal error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ServiceUnavailable:
      description: Service unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          required: true
          schema:
            type: integer
            minimum: 0
  securitySchemes:
    HTTPBearer:
      type: http
      description: Organization API key (sl_…).
      scheme: bearer

````