Run Compute batches
How to submit many independent jobs together, keep every item identifiable, and handle partial completion, cancellation and delivery.
Group independent work first
Use a batch when each job can finish without another job's output. Give every job a stable customer-item identity. A batch groups submissions; it does not create dependent workflow stages or choose physical execution.
Your agent keeps each item's purpose and acceptance rule. The Compute Kit prepares the permitted inputs and connects the approved interface; Lithi handles the admitted jobs and returns each job's state and result metadata for your agent to reconcile.
For dependent work, finish and verify the earlier operation before preparing the next authorized input, quote and approval. Do not use array order to imply a dependency.
Prepare the batch intent
Prepare your approved account, the batch's fixed input and output requirements, a completion policy and a quote for that intent. The batch request uses these exact fields:
Keep the prepared task brief beside the request: frozen instructions and rubric, input snapshot, operation and output schema, stable item IDs, required evidence, and the rule that makes an item acceptable. The brief gives your agent the context for reviewing returned work; the batch fields bind the submitted work and approval. Preserve those identities through retries and result review.
| Field | Meaning |
|---|---|
quote_id | The signed quote identifier for this batch intent |
completion_policy_digest | The digest of the approved policy that defines completion |
items | Complete LiveBoundedLithiJobV1 request bodies with their encrypted input and quote binding |
Keep the policy description beside its digest. Keep account, capability, operation, profile, destination, and correlation fields consistent in every item. A batch is one run over one sealed input: its first item carries sealed_block_manifest, stage_partition and completion_policy once for the batch; later items carry none of those fields, and every item carries its own sealed_binding. Build each job body with Run and follow Compute jobs.
The batch quote and approval cover the complete set of items and the selected completion policy. A batch does not turn dependent operations into one request, and it does not authorize items that were added after approval. Changing an item, destination, deadline, verification requirement or policy means revised work: reconcile the original batch before obtaining a fresh quote and approval. A changed instruction, rubric or output schema is the same kind of deliberate change even when the input IDs stay the same.
Fit the request to its limits
The client accepts 1–100,000 entries in the items array, but every item is a complete LiveBoundedLithiJobV1
body. Measure the serialized request for the limits of the API path you use instead of relying on an
assumed item count.
Split only for a customer-visible reason, such as request size, a distinct policy, or separate result reconciliation. A new batch intent needs its own quote and applicable approval. Do not split to choose Macs or imitate physical runtime packing.
Submit once and save the identity
Submit the batch with its saved Idempotency-Key. Keep the exact body and key before you send it. A
transport retry of the same intent reuses both; it is the same customer-authorized work and does not
create a second charge. A changed input, policy, destination or work is a new intent.
An accepted response includes batch_id, state, total_count, accepted_count, failed_count, digest, and p_next_action. Store the batch ID. Admission for asynchronous handling does not mean every job finished.
Read every result page
Read the current batch state, then read its results with a bounded limit, passing each returned next_cursor unchanged. The state describes recorded progress; a result page does not by itself make the batch complete. Every result identifies its job_id, encrypted artifact, result and evidence digests, and delivery state.
The Go client exposes the same operations as CreateBatch, GetBatch and ListBatchResults; the
last operation accepts a page limit from 1 through 100 and an opaque cursor. A page is an observation
of available results, not proof that the batch has reached its completion policy.
Join results to your saved customer-item mapping through job_id, never array order. When accepted_count + failed_count is below total_count, the remainder is unresolved in that observation. An accepted counter or empty page does not prove complete output.
Handle partial completion and cancellation
A batch completion policy defines what the batch may report as complete. Read individual jobs and events for unresolved items before creating more work. Keep accepted results, failures, and unknown outcomes separate.
If someone requests cancellation, read the current batch and job outcomes. A cancellation request is not confirmed cancellation. Preserve work accepted before the request and reconcile its usage and delivery.
Recover only what remains
If the creation response is lost, reconcile the original batch with its saved body and key before retrying. Do not rotate the key or create a replacement merely to resolve uncertainty.
If accepted output exists but delivery fails, recover delivery through result delivery. For an unresolved input, obtain a fresh quote and approval only after you identify the deliberate new work. Use Compute Help when the existing identity or outcome remains unclear.
Physical attempts inside a batch are not automatically customer billing units. The quote defines the accepted billing unit, while the completion policy defines when the batch may report completion; reconcile usage separately from delivery. Recover a failed delivery against the same accepted artifact instead of creating a replacement job.