Spend caps for unattended AI agents: how Sume bounds each run

A spend cap is the most one unattended agent run may spend on generation. On Sume, every Agent Completion must send generation_spend_cap_usd, every Format run has an effective cap (the Format's own, or one you set up to the $500 platform maximum), and a run can never spend past it.

The rules below come from Sume's Create a run, Errors and spend, Agent Completions, and MCP tools and gates docs pages, read on 2026-09-25.

Why does an unattended agent need a spend cap?

In the Agents chat, an interactive spend-approval prompt protects you. A backend caller has no such prompt: an Agent Completion is an unattended agent with tools and access to your generation wallet, so the cap is the substitute.

Format runs over the API work the same way. A recipe written for chat may pause for a person's approval; over the API nobody is there, so the run is told those approvals are already granted and carries on to the paid step within its spend cap.

How do I set a spend cap on a Format run?

Send generation_spend_cap_usd on POST /v1/formats/{handle}/{slug}/runs. Every Format carries its own cap, readable as generation_spend_cap_usd_micros on GET /v1/formats/…; a Format that never named one reports the platform default of $400. Production long-form runs are typically created with caps around $120, and a single-scene retry with a few dollars.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{
    "input": { "product_url": "https://shop.example.com/p/8823" },
    "generation_spend_cap_usd": 120
  }'

Is a spend cap required on Agent Completions?

Yes. On Agent Completions, generation_spend_cap_usd has no default for POST /v1/agent/completions; omit it and the request fails with 400 invalid_request. Set it to the most you are willing to spend on a single run, and size it from the metered rates on API pricing.

What happens when a run reaches its cap?

Two gates apply, at different times. A Format run that wanted to spend past its cap lands on the generic format_run_failed code, so compare usage.billable_amount_usd_micros with usage.generation_spend_cap_usd_micros on the receipt to see whether the cap stopped it.

• Generation that finished before a cancel or a failure is billed; a later step failing does not refund it.
• A 4xx at create, an idempotent 200 replay, and a skipped run cost nothing.

What does the cap count, and what does it leave out?

The cap bounds metered generation (video, image, avatar, voice, and timeline work) at the rates on API pricing. The receipt reports it as usage.billable_amount_usd_micros, which climbs while the run is in flight, counts both reserved and captured amounts, and settles when the run terminates.

It excludes the agent's own LLM turn, so it is not the run's total cost, and it is a receipt figure, not an invoice: GET /v1/usage and GET /v1/balance are the billing records. usage is null when spend could not be read, which is different from 0. Plans and the wallet are explained in how Sume pricing works.

How do spend limits work on the hosted MCP server?

Hosted MCP tools gate each paid call. There is no mcp:paid scope; spend is governed by the wallet and admission.

• idempotency_key is required on write and paid tools. It is a stable key for transport and dedup, not human approval.
• dry_run=true returns an admission and cost preview without submitting the job. Call again with dry_run omitted or false to submit.
• max_spend_usd is optional and enforced only when you provide it.
• generation_admission_preview is the preview to use before expensive bursts; ordinary single creates do not need it.

{
  "idempotency_key": "avatar-create-2026-07-21-001",
  "dry_run": true,
  "max_spend_usd": 2,
  "payload": {
    "avatar_handle": "studio_presenter",
    "input": { "type": "prompt", "prompt": "A friendly studio presenter in neutral lighting" }
  }
}