API reference

Batch

7 operations, 1 webhook. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

POST/v1/batch

Submit a batch

Paid accounts onlyUses tokens

API key required
Paid accounts only
Uses tokens

Runs one recipe over up to 500 audio files in the background. The call returns 202 at once with a batch_id; follow progress with the status route or receive a batch_completed webhook when the batch ends. Batches are available on paid accounts only; a free-account key receives 403 batch_paid_only.

Each file is charged like a single run of the recipe: 1 token per second of audio at the base rate ($0.10 per minute), and recipes can carry their own per-step rates. Use the estimate route first to see the cost. The account needs a token balance, or auto-recharge turned on, otherwise the call returns 402 insufficient_balance.

Send an Idempotency-Key header to make retries safe: the same key with the same request returns the original batch_id (with meta.idempotent: true) and starts nothing new; the same key with a different request returns 409 idempotency_key_reused.

Capped at 10 requests per minute per account on top of the hourly account budget.

Cost. Charged per file when its run finishes: 1 token per second of audio at the base rate of $0.10 per minute. Recipes can use per-step rates, so check the estimate route first.

curl -X POST "https://api.scarleta.ai/v1/batch" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Idempotency-Key: a-unique-value-per-request" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "rec_1005_cat_spectral",
    "audio_urls": [
      "https://example.com/track-1.wav",
      "https://example.com/track-2.wav"
    ],
    "name": "Morning session",
    "webhook_url": "https://example.com/hooks/scarleta"
  }'

Parameters

Name	Type	Required	Description
Idempotency-Keyheader	string	Optional	1 to 255 visible ASCII characters. Makes the submit safe to retry.

Request body

Name	Type	Required	Description
recipe_idbody	string	Required	The recipe to run on every file, for example `rec_1005_cat_spectral`. Allowed: at least 1 character.
audio_urlsbody	array<string>	Required	HTTPS URLs of the audio files to process, 1 to 500 entries.
namebody	string	Optional	A label for the batch, up to 32000 characters. Returned as `name` by the list route.
messagebody	string	Optional	Older alias of `name`. When both are sent, `name` wins. Allowed: at most 32000 characters.
webhook_urlbody	string	Optional	Where to POST the `batch_completed` event. Must be an https URL that resolves to a public address, at most 4096 bytes.
metadatabody	object	Optional	Free-form JSON object kept with the batch, at most 8192 bytes when serialized. Keys are limited to 64 characters and string values to 2048.

Response fields

Field	Type	Description
batch_id	string	Identifier of the new batch.
status	"IN_QUEUE"

Errors

Status	Code	Description
400	missing_audio_urls	Invalid JSON, a missing or empty `audio_urls` or `recipe_id`, an unacceptable audio or webhook URL, a label or metadata that breaks its limits, or a malformed `Idempotency-Key`.
401	invalid_key	Missing, malformed, unknown or revoked API key.
402	insufficient_balance	No token balance and no auto-recharge.
403	batch_paid_only	The key belongs to a free account, or a file is not owned by your account.
404	not_found	The recipe does not exist or is not visible to your account.
409	idempotency_key_reused	The `Idempotency-Key` was used before with a different request.
413	metadata_too_large	The metadata is over 16384 bytes, or the `webhook_url` is over 4096 bytes.
422	batch_too_large	More than 500 files.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
500	workflow_create_failed	The batch could not be started. Retry with the same `Idempotency-Key`.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "status": "IN_QUEUE"
  },
  "meta": {
    "source": "workflow"
  }
}

202 Accepted. The batch is queued. `meta` has no `request_id`; the `X-Request-ID` header carries the request id.
400 Invalid JSON, a missing or empty `audio_urls` or `recipe_id`, an unacceptable audio or webhook URL, a label or metadata that breaks its limits, or a malformed `Idempotency-Key`.
401 Missing, malformed, unknown or revoked API key.
402 No token balance and no auto-recharge.
403 The key belongs to a free account, or a file is not owned by your account.
404 The recipe does not exist or is not visible to your account.
409 The `Idempotency-Key` was used before with a different request.
413 The metadata is over 16384 bytes, or the `webhook_url` is over 4096 bytes.
422 More than 500 files.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
500 The batch could not be started. Retry with the same `Idempotency-Key`.
503 Temporary platform condition; retry shortly.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: invalid_audio_url, invalid_auth_format, invalid_idempotency_key, invalid_json, invalid_key_format, invalid_message, invalid_metadata, invalid_name, invalid_recipe_id, invalid_webhook_url, media_not_owned, message_too_long, missing_api_key, missing_auth, missing_recipe_id, name_too_long, rate_limit_unavailable, unauthorized, webhook_url_too_large, webhook_validation_unavailable.

GET/v1/batch/{batch_id}

Get a batch

Paid accounts only

API key required
Paid accounts only
No token cost

Returns the live state of one batch: its status, per-state item counters and progress. A batch is final when status is completed, failed, partial or cancelled. Only batches created by your own account can be read; any other id returns 404. Capped at 600 requests per minute per account on top of the hourly account budget.

Cost. Free of charge.

BATCH_ID="YOUR_BATCH_ID"
curl "https://api.scarleta.ai/v1/batch/$BATCH_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
batch_idpath	string	Required	The `batch_id` returned when the batch was submitted. Batches submitted today get a UUID; an older batch can carry an id of the form `batch_<digits>_<hex>`, which is accepted too.

Response fields

Field	Type	Description
message	string	Human-readable progress line.
batch_id	string	Identifier of the batch.
status	"processing" \| "completed" \| "failed" \| "partial" \| "cancelled" \| null	Current state. `processing` until every item is final.
error	string \| null	Summary of why the batch failed, when it did.
total	integer	Items in the batch. Allowed: -9007199254740991 to 9007199254740991.
completed	integer	Items that finished successfully. Allowed: -9007199254740991 to 9007199254740991.
failed	integer	Items that failed. Allowed: -9007199254740991 to 9007199254740991.
cancelled	integer	Items cancelled before they finished. Allowed: -9007199254740991 to 9007199254740991.
pending	integer	Items waiting to start. Allowed: -9007199254740991 to 9007199254740991.
processing	integer	Items running now. Allowed: -9007199254740991 to 9007199254740991.
percent_complete	number	`completed` divided by `total`, as a percentage with one decimal.
actual_cost	number	Tokens charged so far for the batch.
estimated_cost	number \| null	Estimate recorded at submit, when there was one.
created_at	number \| null	Milliseconds since the Unix epoch.
completed_at	number \| null	Milliseconds since the Unix epoch.
webhook_delivery_status	string \| null	State of the `batch_completed` delivery: `in_progress`, `delivered`, `failed`, `skipped` (no `webhook_url`, or the batch was cancelled, which sends no webhook) or `unconfirmed`; null before the batch ends. It describes only the per-request `webhook_url`: addresses registered with `POST /v1/webhooks` are retried the same way, but their outcome is not shown in this field.
webhook_last_attempt_at	number \| null	Milliseconds since the Unix epoch.

Errors

Status	Code	Description
400	invalid_batch_id	`batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	batch_not_found	No batch with this id exists for your account.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "message": "Batch b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7: 100.0% complete (2/2)",
    "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "status": "completed",
    "error": null,
    "total": 2,
    "completed": 2,
    "failed": 0,
    "cancelled": 0,
    "pending": 0,
    "processing": 0,
    "percent_complete": 100,
    "actual_cost": 40,
    "estimated_cost": null,
    "created_at": 1791333870854,
    "completed_at": 1791333895009,
    "webhook_delivery_status": "delivered",
    "webhook_last_attempt_at": 1791333895229
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 `batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401 Missing, malformed, unknown or revoked API key.
404 No batch with this id exists for your account.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

DELETE/v1/batch/{batch_id}

Cancel a batch

Paid accounts only

API key required
Paid accounts only
No token cost

Stops a batch that is still running: items that have not finished are cancelled and their work is stopped. Items that already finished keep their results and their charges. A batch that has already reached a final state returns 409 batch_already_final. Capped at 10 requests per minute per account on top of the hourly account budget.

Cost. Free of charge. Items that already finished stay charged.

BATCH_ID="YOUR_BATCH_ID"
curl -X DELETE "https://api.scarleta.ai/v1/batch/$BATCH_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
batch_idpath	string	Required	The `batch_id` returned when the batch was submitted. Batches submitted today get a UUID; an older batch can carry an id of the form `batch_<digits>_<hex>`, which is accepted too.

Response fields

Field	Type	Description
message	string
batch_id	string	Identifier of the batch.
cancelled	integer	Items this call cancelled. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
400	invalid_batch_id	`batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	batch_not_found	No batch with this id exists for your account.
409	batch_already_final	The batch had already reached a final state. `error.details.status` holds that state.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "message": "Batch b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7 cancellation requested. 2 items cancelled.",
    "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "cancelled": 2
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 `batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401 Missing, malformed, unknown or revoked API key.
404 No batch with this id exists for your account.
409 The batch had already reached a final state. `error.details.status` holds that state.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

GET/v1/batch/{batch_id}/results

Get batch results

Paid accounts only

API key required
Paid accounts only
No token cost

Returns the per-file results of a batch, 50 items per page by default. Page with offset and limit while has_more is true. The keys inside each raw_results depend on the recipe that ran. Capped at 600 requests per minute per account on top of the hourly account budget.

Cost. Free of charge.

BATCH_ID="YOUR_BATCH_ID"
curl "https://api.scarleta.ai/v1/batch/$BATCH_ID/results" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
batch_idpath	string	Required	The `batch_id` returned when the batch was submitted. Batches submitted today get a UUID; an older batch can carry an id of the form `batch_<digits>_<hex>`, which is accepted too.
offsetquery	integer	Optional	Items to skip. Defaults to 0. Allowed: 0 to 9007199254740991.
limitquery	integer	Optional	Items per page. Defaults to 50; values above 100 are clamped to 100. Allowed: 1 to 100.

Response fields

Field	Type	Description
message	string
batch_id	string	Identifier of the batch.
items	array<object>
items[].item_id	string	Identifier of this item attempt.
items[].item_index	integer \| null	Position of the file in `audio_urls`, starting at 0. Allowed: -9007199254740991 to 9007199254740991.
items[].audio_url	string	The file this item processed.
items[].display_name	string \| null	The file's library name, when it is in your library; null otherwise.
items[].reference_url	string \| null
items[].status	"pending" \| "processing" \| "completed" \| "failed" \| "cancelled"
items[].raw_results	object \| null	Output of the recipe for this file. The keys depend on the recipe that ran.
items[].error	string \| null	Why the item failed, when it did.
items[].cost	number \| null	Tokens charged for this item.
items[].duration_ms	number \| null	How long the item took, in milliseconds.
items[].retry_count	integer \| null	How many times this item has been retried. Allowed: -9007199254740991 to 9007199254740991.
total	integer	Items in the batch. Allowed: -9007199254740991 to 9007199254740991.
offset	integer	Allowed: -9007199254740991 to 9007199254740991.
limit	integer	Allowed: -9007199254740991 to 9007199254740991.
has_more	boolean	True when another page follows.
filters_applied	object
filters_applied.status_filter	string

Errors

Status	Code	Description
400	invalid_batch_id	`batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	batch_not_found	No batch with this id exists for your account.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "message": "Returning 1 items (offset 0)",
    "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "items": [
      {
        "item_id": "3f2a9c1e-7b64-4c0d-8e21-5a6b7c8d9e0f",
        "item_index": 0,
        "audio_url": "https://example.com/track-1.wav",
        "reference_url": null,
        "status": "completed",
        "raw_results": {
          "recipe_id": "rec_1005_cat_spectral",
          "status": "COMPLETED"
        },
        "error": null,
        "cost": 20,
        "duration_ms": 8120,
        "retry_count": 0
      }
    ],
    "total": 2,
    "offset": 0,
    "limit": 50,
    "has_more": true,
    "filters_applied": {
      "status_filter": "all"
    }
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 `batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401 Missing, malformed, unknown or revoked API key.
404 No batch with this id exists for your account.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

POST/v1/batch/{batch_id}/retry

Retry failed items of a batch

Paid accounts onlyUses tokens

API key required
Paid accounts only
Uses tokens

Re-queues the items of a finished batch that failed, as new attempts, and reopens the batch. Only a batch whose status is failed, partial or cancelled can be retried; any other status returns 409 batch_not_retryable. An item that has already been retried max_retries times is left as failed and counted in permanently_failed. The body is optional. Capped at 10 requests per minute per account on top of the hourly account budget.

Cost. Re-queued items are charged again when they finish, at the same per-file rate as the original run.

BATCH_ID="YOUR_BATCH_ID"
curl -X POST "https://api.scarleta.ai/v1/batch/$BATCH_ID/retry" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_retries": 2
  }'

Parameters

Name	Type	Required	Description
batch_idpath	string	Required	The `batch_id` returned when the batch was submitted. Batches submitted today get a UUID; an older batch can carry an id of the form `batch_<digits>_<hex>`, which is accepted too.

Request body

Name	Type	Required	Description
max_retriesbody	integer	Optional	Highest number of times one item may be retried, 1 to 10. Defaults to 2.

Response fields

Field	Type	Description
message	string
batch_id	string	Identifier of the batch.
requeued	integer	Items put back in the queue. Allowed: -9007199254740991 to 9007199254740991.
permanently_failed	integer	Failed items that were not re-queued because they reached `max_retries`. Allowed: -9007199254740991 to 9007199254740991.
superseded	boolean	True when a cancel or another retry changed the batch while this call ran, so nothing was started.

Errors

Status	Code	Description
400	invalid_max_retries	The body is not a JSON object, `max_retries` is not an integer in range, or `batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	batch_not_found	No batch with this id exists for your account. If the batch exists but its recipe was deleted, the code is `not_found` instead (past results are kept).
409	batch_not_retryable	The batch is still running or already completed.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
500	workflow_create_failed	The retry could not be started.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "message": "Retry results: 1 items requeued, 0 permanently failed (already at 2 retries)",
    "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "requeued": 1,
    "permanently_failed": 0
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 The body is not a JSON object, `max_retries` is not an integer in range, or `batch_id` is neither a UUID nor a legacy `batch_<digits>_<hex>` id.
401 Missing, malformed, unknown or revoked API key.
404 No batch with this id exists for your account. If the batch exists but its recipe was deleted, the code is `not_found` instead (past results are kept).
409 The batch is still running or already completed.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
500 The retry could not be started.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: batch_recipe_missing, batch_tenant_missing, invalid_auth_format, invalid_batch_id, invalid_json, invalid_key_format, missing_api_key, missing_auth, not_found, rate_limit_unavailable, unauthorized.

POST/v1/batch/estimate

Estimate the cost of a batch

Paid accounts only

API key required
Paid accounts only
No token cost

Returns the token cost of running a recipe over a list of files, per file and in total, without starting anything and without charging. Batches are available on paid accounts only; a free-account key receives 403 batch_paid_only. Accepts the same recipe_id and audio_urls as submit, at most 500 files. A file whose length cannot be read contributes 0 and reports duration_seconds: null. Capped at 600 requests per minute per account on top of the hourly account budget.

Cost. Free of charge: estimating never spends tokens.

curl -X POST "https://api.scarleta.ai/v1/batch/estimate" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "rec_1005_cat_spectral",
    "audio_urls": [
      "https://example.com/track-1.wav",
      "https://example.com/track-2.wav"
    ]
  }'

Request body

Name	Type	Required	Description
recipe_idbody	string	Required	The recipe to run on every file, for example `rec_1005_cat_spectral`. Allowed: at least 1 character.
audio_urlsbody	array<string>	Required	HTTPS URLs of the audio files to process, 1 to 500 entries.

Response fields

Field	Type	Description
message	string
recipe_id	string
total_cost	number	Tokens the whole batch would cost.
file_count	integer	Allowed: -9007199254740991 to 9007199254740991.
per_file	array<object>
per_file[].audio_url	string
per_file[].duration_seconds	number \| null
per_file[].cost	number

Errors

Status	Code	Description
400	missing_audio_urls	The body is not valid JSON, `recipe_id` or `audio_urls` is missing, or a URL is not an acceptable public audio URL.
401	invalid_key	Missing, malformed, unknown or revoked API key.
403	batch_paid_only	The key belongs to a free account.
404	recipe_not_found	The recipe does not exist or is not visible to your account.
422	batch_too_large	More than 500 files.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "message": "Estimated cost for 2 file(s) with recipe rec_1005_cat_spectral",
    "recipe_id": "rec_1005_cat_spectral",
    "total_cost": 40,
    "file_count": 2,
    "per_file": [
      {
        "audio_url": "https://example.com/track-1.wav",
        "duration_seconds": 4,
        "cost": 20
      },
      {
        "audio_url": "https://example.com/track-2.wav",
        "duration_seconds": 3.2,
        "cost": 20
      }
    ]
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 The body is not valid JSON, `recipe_id` or `audio_urls` is missing, or a URL is not an acceptable public audio URL.
401 Missing, malformed, unknown or revoked API key.
403 The key belongs to a free account.
404 The recipe does not exist or is not visible to your account.
422 More than 500 files.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_audio_url, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, missing_recipe_id, rate_limit_unavailable, unauthorized.

GET/v1/batches

List batches

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns your most recent batches, newest first, each with its item counters and the tokens charged so far. Page past the first limit batches with offset; total is how many batches you have in all. Returns an empty list for a free account, which cannot create batches. Capped at 600 requests per minute per account on top of the hourly account budget.

Cost. Free of charge.

curl "https://api.scarleta.ai/v1/batches" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
limitquery	integer	Optional	Rows to return. Defaults to 50; values above 100 are clamped to 100. Allowed: 1 to 100.
offsetquery	integer	Optional	Batches to skip, newest first. Defaults to 0; a negative or non-numeric value is read as 0. Allowed: 0 to 9007199254740991.

Response fields

Field	Type	Description
message	string
batches	array<object>
batches[].batch_id	string	Identifier of the batch. Batches submitted today get a UUID. An older batch can carry an id of the form `batch_<digits>_<hex>`: it is listed here and every batch route accepts it.
batches[].status	"processing" \| "completed" \| "failed" \| "partial" \| "cancelled" \| null	Current state of the batch.
batches[].recipe_id	string \| null
batches[].name	string \| null	The label sent as `name` (or `message`) at submit, if any.
batches[].total_items	integer \| null	Allowed: -9007199254740991 to 9007199254740991.
batches[].completed_items	integer	Items that finished successfully. Allowed: -9007199254740991 to 9007199254740991.
batches[].failed_items	integer	Items that failed. Allowed: -9007199254740991 to 9007199254740991.
batches[].cancelled_items	integer	Items cancelled before they finished. Allowed: -9007199254740991 to 9007199254740991.
batches[].created_at	number \| null	When the batch was submitted, in milliseconds since the Unix epoch.
batches[].completed_at	number \| null	When the batch reached a final state, in milliseconds since the Unix epoch.
batches[].actual_cost	integer	Tokens charged so far for this batch's items; 0 when nothing was charged. Allowed: -9007199254740991 to 9007199254740991.
count	integer	Allowed: -9007199254740991 to 9007199254740991.
total	integer	How many batches you have in all, which can be more than the page returned. On a page past the end it is the offset you asked for. Allowed: -9007199254740991 to 9007199254740991.
offset	integer	The offset this page starts at. Allowed: -9007199254740991 to 9007199254740991.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "message": "Returning 1 batches",
    "batches": [
      {
        "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
        "status": "completed",
        "recipe_id": "rec_1005_cat_spectral",
        "name": "Morning session",
        "total_items": 2,
        "completed_items": 2,
        "failed_items": 0,
        "cancelled_items": 0,
        "created_at": 1791333870854,
        "completed_at": 1791333895009,
        "actual_cost": 120
      }
    ],
    "count": 1,
    "total": 1,
    "offset": 0
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.

EVENTbatch_completed

Webhook: Batch completed

Sent by Scarleta

Sent when a batch ends as completed, failed or partial: to the webhook_url of the batch, if it has one, and to every address registered with POST /v1/webhooks. The body is a JSON object with exactly the fields below. Each delivery carries X-Scarleta-Timestamp (Unix seconds) and X-Scarleta-Signature (v1= followed by the lowercase hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with your signing secret from GET /v1/webhooks/signing-secret). Reject deliveries whose timestamp is more than 300 seconds from your clock. For one day after a rotation a delivery also carries X-Scarleta-Signature-Previous, signed with the previous secret; a receiver that has not switched to the new secret yet can verify that header with its old secret. Addresses registered with POST /v1/webhooks receive this event too, signed the same way; an address identical to the webhook_url is delivered once.

Your endpoint must answer with a 2xx status within 10 seconds. Scarleta makes up to 3 attempts, waiting 2 s and 4 s before the second and third; redirects are not followed. Targets that are not public https endpoints are never called. A batch you cancel sends no batch_completed: its webhook_delivery_status is skipped, and the cancel call itself is the answer. If you retry a batch, the webhook is sent when the retry ends. Each completion starts one delivery sequence to the webhook_url of the batch and never a second one, but inside that sequence an attempt that timed out or got a non-2xx answer is sent again with the same body, and the earlier attempt may already have reached you: de-duplicate by batch_id and completed_at. Registered addresses are delivered at least once, on a best-effort basis: a failed delivery to a registered address can also be sent again when the same completion is replayed, so de-duplicate by batch_id and completed_at there too. webhook_delivery_status on the batch shows the outcome of the delivery to its webhook_url only; registered addresses are retried the same way, but their outcome is not shown in that field.

Set by the webhook_url field of Submit a batch.

Payload

Field	Type	Description
event	"batch_completed"
batch_id	string	The batch that ended.
status	"completed" \| "failed" \| "partial"	How the batch ended.
total_items	integer	Items in the batch. Allowed: -9007199254740991 to 9007199254740991.
completed_items	integer	Allowed: -9007199254740991 to 9007199254740991.
failed_items	integer	Allowed: -9007199254740991 to 9007199254740991.
cancelled_items	integer	Allowed: -9007199254740991 to 9007199254740991.
actual_total_cost	number	Tokens charged for the whole batch.
completed_at	number	When the batch ended, in milliseconds since the Unix epoch.

Example payload

{
  "event": "batch_completed",
  "batch_id": "b1a2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
  "status": "completed",
  "total_items": 2,
  "completed_items": 2,
  "failed_items": 0,
  "cancelled_items": 0,
  "actual_total_cost": 40,
  "completed_at": 1791333895009
}