Agent Completion 400: generation_spend_cap_usd has no default

Add generation_spend_cap_usd to the body. On POST /v1/agent/completions it is required, it has no default, and a request without it fails with a 400. That is deliberate: an Agent Completion can open a sandbox, call tools and generate media, and Sume wants a number from you before any of that can spend money (Sume docs: Agent Completions, read 2026-10-06).

This differs from a Format run, where omitting the cap lets the Format's own cap apply, which defaults to $400. A completion stores nothing and belongs to no Format, so there is no cap to fall back on.

A body that works

Send exactly one of instruction or messages, plus the cap. The model field accepts only sume-agent, and omitting it gives you the same agent. The call returns 202 with an agent.run receipt, an id beginning agrun_, a status_url and a cancel_url. It is asynchronous, so you poll rather than wait on the connection.

import os, requests

H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
body = {
    "instruction": "Write a 20 word caption for a ceramic mug photo.",
    "generation_spend_cap_usd": 2,
}
r = requests.post("https://api.sume.com/v1/agent/completions",
                  json=body, headers=H, timeout=30)
print(r.status_code)
run = r.json()["data"]
print(run["id"], run["status"])
print(run["status_url"])

Choosing the number

Do not pick a round number out of the air. Run the task once with a generous cap, read usage on the terminal receipt, and set the production cap a little above the worst real run. Too low and a legitimate run stops partway. Too high and the cap stops protecting you. The cap bounds generation spend; wallet balance and workspace limits still apply separately.

A text-only task such as the caption above should need little. A task that asks the agent to generate video is a different order of magnitude, so keep separate caps for separate kinds of task rather than one global number.

If the 400 persists

Read the error body before changing anything. Common neighbors of a missing cap are sending both instruction and messages, which is rejected, and sending an assistant turn in messages, which the API rejects instead of ignoring. A 403 is a different problem: it means the key lacks the agent_completions scopes or is a service-account key, and a new personal key with those scopes is the fix.

Add an Idempotency-Key so a retry after a timeout returns the original receipt with idempotency_hit true rather than starting a second paid run. Reusing a key with a different body returns 409 idempotency_conflict.

Related limits worth knowing

Attachments accept up to 30 images, input is written to a file and read as data, and output_schema binds the result to a shape you choose. A primary_output_key names the headline result. None of these change the cap rule, but each is a reason to read the 400 body carefully, since several fields can be wrong at once.

Idempotency on the first call

The cap is the first thing to add, and the Idempotency-Key is the second. Without it, a network timeout on the create call leaves you not knowing whether a run exists. With it, you repeat the call safely and either start the run or get the original receipt back.

Derive the key from the task, for example a hash of the instruction plus the date, so the same task on the same day never runs twice by accident, while a deliberate rerun with a new date or version does.