Skip to main content
The Batch API supports larger and longer-running asynchronous workloads. Submit inputs, poll the batch, then retrieve each completed item’s result.

​
Submit inputs

Choose the inference operation with endpoint and put its inputs in payload. Each payload entry becomes a task.
Save data.batch_id from the response. A one-item batch also returns data.task_id. Task IDs append a zero-padded index, such as <batch_id>-00000. For repeated payloads, ordering is by repeat first, then position within payload.

​
Track progress

Poll List with the saved batch_id:
The aggregate batch state is in_progress, done, failed, or cancelled. An aggregate done means all tasks are terminal; some or all tasks may have failed. A cancelled batch can still contain running tasks. counts covers the whole batch and omits states with zero items. Set include_responses: true to retrieve an item page, then follow the returned cursor until it is null. The default page size is 100 and the maximum is 1000. A full final page can require one additional empty-page request. A status filter narrows the item page, while counts remain batch-wide. Tasks that have not started 24 hours after the batch was submitted are cancelled and never charged; tasks already running finish normally. Status and List return this deadline as data.expires_at.

​
Retrieve results

Call Status with a task_id from the submission response or an item page:
When the task is done, data.response contains an inline result object, inline text, or a signed URL to download it, depending on the endpoint. For fold_max_accuracy, it is a signed URL for the folding-result JSON. Other outputs, when present, are signed URLs in data.artifacts, keyed by artifact name. List responses can include inline results but omit artifact URLs; externally stored results are indicated by response_available: true. Download signed URLs without the Biohub bearer token. Read status again to refresh expired URLs. When present, data.artifacts_expire_in gives the shortest artifact URL lifetime in seconds.

​
Result retention

Results are kept for 31 days after the batch is submitted, after which they are deleted. Status and List return the deadline as data.results_expire_at. After that, Status returns 410 and List still reports each item’s status but omits response, response_available, and error.

​
Responses and failures

A successful HTTP operation returns this envelope:
Route errors carry message instead:
Authentication failures can use error instead of message; handle both shapes. Retain request_id when reporting a failed call. The envelope’s status describes the HTTP operation, while data.status describes the job. An HTTP 200 can report a failed task; inspect data.error on the status response. Failure to read status does not mean the task failed. Passing a batch ID to Status returns 404 with instructions to use List or an item ID.

​
Cancel

Cancel accepts exactly one of task_id or batch_id. It affects queued tasks only. Running tasks continue and retain their usage charges. A batch with no cancellable work returns 409; cancelling an already cancelled batch succeeds.