Compute
Run a batch
How to submit many independent items, how a multi-step chain is expressed, and which of the two you actually need.
On this page
What works today
POST /v1/batches returns 503 UNAVAILABLE. Reading an existing batch and listing its results do answer, but nothing can create one, and no batch has ever run.
Multi-step chains are further out than batches, for a reason described at the end of this page that is worth reading before you plan around them.
Batches and chains are different axes
These get confused constantly, so the distinction is worth stating plainly:
- A batch is fan-out. Many items, all the same shape, independent of one another, no ordering between them.
- A chain is ordering within one piece of work. Several steps where a later step consumes what an earlier step produced.
They compose. A batch of chains is many independent pieces of work that each have internal steps. But a batch is never how you express ordering, and a chain is never how you express volume.
If your items do not depend on each other, you want a batch. If step two needs step one's output, you want a chain.
Batches
A batch submits homogeneous, execution-equivalent items. Every item shares one quote and one completion policy, and each item's evidence is isolated from the others so one failure does not contaminate the rest.
Do not mix accounts, releases, schemas, verification modes, or side-effect classes within a batch. Items that are not execution-equivalent belong in separate batches.
On batch size: treat the request-body ceiling as the real limit. The 64 KiB cap applies to a batch exactly as it does to any other request, and a batch that inlines full job bodies reaches it after a few dozen items. Plan for tens of items per request, not thousands.
Chains
A multi-step chain is expressed as a task recipe: an ordered list of steps, each with an id, an ordinal, an operation, its dependencies, its input and output digests, and its own bounds — plus aggregate bounds for the whole recipe.
Two things about how steps link, both of which are easy to get backwards:
Steps link by digest, not by artifact id. Step two references step one's output_digest in its own input_digests. The input_artifact_ids field stays pointed at the original input asset for every step in the chain — it does not advance as the chain progresses. If you model the chain as artifact ids flowing from step to step, you have it wrong.
A recipe plans work; it does not authorise it. A recipe carries authorizes_execution: false and grants nothing — no execution, no credentials, no provider access, no spend. It describes a shape. The work is still submitted as a job, and the recipe binds to that job by digest rather than the job embedding the recipe.
That means a chain is one job carrying a pipeline capability, not a series of jobs you submit one after another. A job is structurally single-step: it names one capability and one operation, and there is no field in it for steps.
The limit worth knowing before you plan
The recipe format admits seven operations. Every capability in the current catalogue declares exactly one operation, verify.
The practical consequence: a chain whose steps are genuinely different kinds of work — transcribing, then analysing what was transcribed — has no way to say so today. The operation vocabulary the recipe format offers and the vocabulary the catalogue actually declares have not been reconciled. This is a known gap, not a subtlety of the format, and we would rather record it here than have you discover it after building against the recipe shape.
Related
- Submit work — the single-job contract a batch item follows
- Capabilities — the operations the catalogue currently declares
- Errors — what an inhomogeneous batch returns