Spend

Spend is what an agent’s model calls cost, in US dollars. Those calls are billed to your own model provider, so the platform shows you the amounts: it prices every call from the rates the llm connection declares, records the result per turn and per day, and lets you put a spend cap on a workflow so a flood of firings cannot spend without limit.

Rates come from the connection

The platform holds no price list. An llm connection declares its own rates, in US dollars per 1,000,000 tokens, the unit providers publish their prices in. On the connection form they are the Rates in USD per 1M tokens table, one row per model with Input / 1M, Output / 1M, Cache read / 1M and Cache write / 1M; in the connection they are its pricing block:

pricing:              # illustrative figures; enter your provider's own
  gpt-6.1-sol:        # a model id, or a key contained in model ids
    input: 2
    output: 10
    cacheRead: 0.1
    cacheWrite: 2.5
  default:            # every other model this endpoint serves
    input: 1
    output: 4

A model is priced by its exact id first, then by the longest declared key its id contains, so one key covers every revision of a model family, then by default. The cache rates are optional; an empty one is charged at the input rate, so a cache read reads higher than the provider bills it and a cache write, which some providers bill above the input rate, may read lower. Rates belong to the connection, so they are inherited with it by child environments, and an environment that replaces the connection replaces its rates. See Connections.

Spend that cannot be measured

The platform never assumes a price. A call it cannot price records its tokens and no amount, and every figure that contains one is marked incomplete. There are three causes, counted per model and kept apart because they are fixed differently:

Cause	What fixes it
No rate is declared for the model	Add a rate, or a `default`, on the connection
The provider did not report which model ran	Nothing you enter: adding a rate does not help
The provider reported no usage at all	Nothing you enter: not even the tokens are known

The LLM card on the Agent page warns before any spend when the selected model has no rate on its connection: spend on it cannot be measured, and a spend cap is not enforced for it.

How spend is recorded

Spend is recorded as each model call completes, one record per turn and per UTC day. A turn that parks and resumes adds each segment to its record, and a turn that runs across midnight records each call against the day it was made. A turn that made no model call records nothing. The records are kept apart from sessions, so deleting a session does not change what an agent is recorded to have spent.

Every call adds to three running totals at once: the agent’s, the environment’s, and the total of the workflow the turn started in that environment. A child session’s calls count toward the workflow that was started, the entry workflow, because a child session spends on behalf of the state that dispatched it.

Where you see spend

Model Spending, a section of the Environment page, shows the environment over the last 7, 30 or 90 days: Spend per day, and Spend per workflow, most first, each beside the spend caps that bound it here, how much of each the current period has used, and when it resets.
The workflows list on the Workflows page has a Spend (30 days) column.
In a session’s detail panel, Session spend totals the session, and each turn shows its Spend, as recorded so far while the turn can still add to it.

Every figure that contains calls that could not be priced says how many, and Model Spending names the models and the cause under Some calls could not be priced.

Spend caps

A spend cap is held on one scope: a workflow within one environment. The agent and the environment have their totals reported, and carry no cap of their own.

Set caps in the editor, in the workflow’s settings, under Spend caps → Add a spend cap: pick a period and an amount in US dollars greater than zero. A workflow may carry one cap per period, so up to three. Caps are stored on the environment, not in workflow.yaml, so the same workflow is capped and counted separately in each environment, and promoting does not carry a cap. A cap names its workflow by slug; one whose slug the environment’s workflows do not hold bounds nothing and is listed as — no such workflow.

Periods

A cap accumulates in one period, a UTC calendar bucket, and resets on its boundary:

Period	Starts
day	at midnight UTC
week	on Monday at midnight UTC
month	on the first of the month at midnight UTC

Every period is counted whether or not a cap names it, so a cap added partway through a period is measured against everything that period already recorded. A change to a cap applies to the next check.

What a cap refuses

Once a workflow’s spend for the current period has reached one of its caps, work that starts that workflow in that environment is refused at three points:

At submit: the request is refused with HTTP 429, its Retry-After header giving the seconds until the period resets, and no turn is created or queued.
At pickup: a queued turn is failed before it makes any model call.
After each model call: a running turn makes no further call and is failed. What it already did is not undone, and the session cannot be continued.

A running turn is the only way spend passes a cap, and only by the calls in flight. When several caps are reached, the shortest period is the one named. Every refusal names the workflow and its environment, the cap, the spend so far in the period, and when the period resets.

A child session is never refused by its own workflow’s cap while it runs as a dispatch: it is bounded by the caps of the entry workflow. A workflow that is also started directly, by a trigger firing for instance, is bounded by its own caps for that traffic. Evaluations and replayed firings spend the same money as any other work and are refused by the same caps. An evaluation over a reached cap is not started; one that reaches a cap while it runs lets the case in flight run to its end, fails it, and reports the cases not yet started as not run, so its overshoot is bounded by one case. See Evaluations.

Spend and Usage

The design agent is different: its model is the platform’s, and the platform pays for it. What you see of it is Usage, the token counts of a turn, shown under each settled turn’s message with the input, output and cached breakdown one step away, and never an amount of money. The platform bounds the design agent with a daily limit per organization and per person; a refusal says whose limit was reached and that the design agent is available again after midnight UTC. See Design agent.