Batches
Routes in this group. Authentication, scope and rate limit errors apply to every route and are on the errors page.
GET/batches/{batchId}
Read a batch's status.
- Scope
batches:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
batchId | path | string | Yes |
Request. Path: the batch id. Needs batches:read.
Returns. batchId, status, reason, counts of units by state, assets, credits (held, settled, total), nextAfter (the latest event number), resultReady, createdAt, and children and parentBatchId when a large manifest was split.
Errors specific to this route. 404 batch_not_found. Authentication, scope and rate limit errors apply to every route.
POST/batches/{batchId}/cancel
Cancel a batch.
- Scope
batches:cancel- Rate bucket
write, 60 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
batchId | path | string | Yes |
Request. No body. Needs batches:cancel. A batch that already ended is returned unchanged.
Returns. The batch status document. An active batch moves to canceling and then canceled; one waiting for a new approval is canceled at once.
Errors specific to this route. 404 batch_not_found. Authentication, scope and rate limit errors apply to every route.
GET/batches/{batchId}/events
Read a batch's event log, oldest first.
- Scope
batches:read- Rate bucket
read, 240 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
batchId | path | string | Yes | |
after | query | integer | No | min 0, default 0 |
Request. Query: after, the last event number you have seen (default 0). Returns up to 500 events.
Returns. batchId, events (seq, type, unitKey, payload, createdAt), nextAfter (pass it as after next time) and hasMore.
Errors specific to this route. 404 batch_not_found. Authentication, scope and rate limit errors apply to every route.
GET/batches/{batchId}/receipt
Read the cost receipt of one batch.
- Scope
results:read- Rate bucket
read, 240 a minute per key- Availability
- Answers 404 not_found where the streamlining flag is off.
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
batchId | path | string | Yes |
Request. Path: the batch id. Needs results:read. This route answers 404 not_found where the streamlining flag is off.
Returns. Credits (held, settled, total), the measured attempts, costs by category, and one line per file with its recipe, state, reason, a readable detail for a failure that has one, credits, input rights and whether it was reused from an earlier batch.
Errors specific to this route. 404 batch_not_found, 404 not_found. Authentication, scope and rate limit errors apply to every route.
GET/batches/{batchId}/wait
Long poll: return when the batch has a new event, reaches an end state, or the timeout passes.
- Scope
batches:read- Rate bucket
read, 240 a minute per key- Availability
- Answers 404 not_found where the streamlining flag is off.
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
batchId | path | string | Yes | |
after | query | integer | No | min 0, default 0 |
timeout | query | number | No | min 0, max 30, default 30 |
Request. Query: after (default 0) and timeout in seconds (0 to 30, default 30). Needs batches:read. This route answers 404 not_found where the streamlining flag is off.
Returns. Everything GET /batches/{batchId} returns, plus events, nextAfter, hasMore and timedOut. timedOut is true when nothing happened before the timeout; ask again with the same nextAfter. Answers 204 with no body if the client disconnected.
Errors specific to this route. 404 batch_not_found, 404 not_found. Authentication, scope and rate limit errors apply to every route.
POST/projects/{slug}/batches
Approve a quote and start the batch.
- Scope
batches:submit- Rate bucket
submit, 12 an hour per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes | |
Idempotency-Key | header | string | No | Required in practice: 1 to 64 printable ASCII characters. The same key with the same approval returns the existing batch; the same key with a different approval is 409 idempotency_conflict. The schema marks it optional because the route checks it itself and answers 422 idempotency_key_required. |
Request. JSON body, BatchRequest below, plus an Idempotency-Key header. planSha256 from the quote and an explicit maxCredits ceiling are required. With dryRun true the call returns a quote and creates nothing. Needs batches:submit and uses the submit bucket.
Body model BatchRequest. Unknown fields are refused.
| Field | Type | Required | Limits |
|---|---|---|---|
manifest | object | Yes | |
inputSetId | string | No | max length 36 |
options | BatchOptions | No | |
maxCredits | integer | No | min 0, max 2147483647, default 0 |
planSha256 | string | No | pattern ^[a-f0-9]{64}$ |
dryRun | boolean | No | default false |
Returns. batchId, status, the quote that was approved and created. 201 for a new batch, 200 when the same Idempotency-Key and approval replay an existing one.
Errors specific to this route. 422 idempotency_key_required, 422 quote_required, 409 quote_changed, 402 credit_ceiling_exceeded, 402 key_batch_credit_cap, 402 key_daily_credit_cap, 402 project_budget_exceeded, 409 lane_paused_for_problem, 422 partial_plan_refused, 409 idempotency_conflict, 429 active_batch_limit, 429 plan_submit_limit, 429 rate_limited, 422 invalid_manifest, 422 project_mismatch, 413 request_too_large. Authentication, scope and rate limit errors apply to every route.
POST/projects/{slug}/batches/quote
Plan a batch and price it. Nothing is created or charged.
- Scope
batches:quote- Rate bucket
write, 60 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes |
Request. JSON body, QuoteRequest below. manifest.project.slug must equal the slug in the path. Needs batches:quote.
Body model QuoteRequest. Unknown fields are refused.
| Field | Type | Required | Limits |
|---|---|---|---|
manifest | object | Yes | |
inputSetId | string | No | max length 36 |
options | BatchOptions | No |
Returns. The quote: manifestSha256, planSha256, totalCredits, counts, assets with per file states, issues, unpricedUnits, approvable, and caps (the per-batch cap, remaining daily credits and project budget that would bind a submit). Send planSha256 back on submit.
Errors specific to this route. 422 invalid_manifest, 422 invalid_request, 422 project_mismatch, 404 input_set_not_found, 413 request_too_large, 404 project_not_found. Authentication, scope and rate limit errors apply to every route.
POST/projects/{slug}/lint
Check a manifest and its inputs without a quote.
- Scope
batches:quote- Rate bucket
write, 60 a minute per key- Availability
- Answers 404 not_found where the streamlining flag is off.
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes |
Request. JSON body, QuoteRequest below: manifest, optional inputSetId, optional options. Needs batches:quote. This route answers 404 not_found where the streamlining flag is off.
Body model QuoteRequest. Unknown fields are refused.
| Field | Type | Required | Limits |
|---|---|---|---|
manifest | object | Yes | |
inputSetId | string | No | max length 36 |
options | BatchOptions | No |
Returns. valid (false when any issue has severity error), manifestId, manifestRevision, manifestSha256, issues, and the issues grouped per asset. Lint reports problems in the body with status 200; it does not use an error status for an invalid manifest.
Errors specific to this route. 404 not_found, 413 request_too_large, 422 invalid_manifest, 422 invalid_request, 422 project_mismatch, 404 project_not_found. Authentication, scope and rate limit errors apply to every route.
POST/projects/{slug}/resize
Resize assets uniformly: a preview, or a manifest and its 0-credit quote.
- Scope
batches:quote- Rate bucket
write, 60 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes |
Request. JSON body (at most 64 KB): collection or assets (up to 100, each with its own factor), or one factor for all; optional texture (nearest or reduce; repaint is not offered yet), presentation scale_all, dryRun, manifestId. Needs batches:quote.
Returns. With dryRun: dryRun, preview and refused. Otherwise the resize manifest with its quote (0 credits, with caps) and how to submit it: POST it to /batches with planSha256, maxCredits 0 and an Idempotency-Key. Any asset that cannot be resized refuses the whole request with 422 resize_refused and the preview.
Errors specific to this route. 422 invalid_request, 404 project_not_found, 404 collection_not_found, 422 resize_no_assets, 422 resize_too_many_assets, 422 resize_nonuniform, 422 resize_presentation_unavailable, 422 model_repaint_unavailable, 422 resize_source_manifest_unavailable, 422 resize_parent_unavailable, 422 resize_refused. Authentication, scope and rate limit errors apply to every route.
POST/projects/{slug}/restore
Restore an asset's files to an older version: a manifest and its 0-credit quote.
- Scope
batches:quote- Rate bucket
write, 60 a minute per key
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
slug | path | string | Yes |
Request. JSON body (at most 64 KB): asset, and toVersion (the model file's version) or files (up to 64 file ids); optional dryRun, manifestId. Needs batches:quote.
Returns. With dryRun: dryRun and preview. Otherwise the restore manifest with its quote (0 credits, with caps) and how to submit it: POST it to /batches with planSha256, maxCredits 0 and an Idempotency-Key.
Errors specific to this route. 422 invalid_request, 404 project_not_found, 404 asset_not_found, 422 restore_version_required, 404 restore_version_not_found, 404 restore_file_not_found, 422 restore_nothing_to_do. Authentication, scope and rate limit errors apply to every route.