Skip to main content
idempotencyKey is an optional caller-supplied string that makes a submission deduplicating. Send the same key twice and the second submission resolves to the task the first one created rather than queuing new work.
Omit it and you get no deduplication — every submission creates a new task. That is a legitimate choice for one-off queries; it is the wrong choice for anything a cron or a retrying worker might submit twice.
A good key is deterministic from the work itself, not from the attempt. Composing the identifiers that define the unit of work — "{jobId}:{promptId}:{engine}" — means a retry naturally reproduces the same key.

​
Single and batch differ on purpose

This is the one place the two endpoints diverge, and it trips people up.
The single-task endpoint keeps explicit-create semantics: you asked to create a task, the task already exists, that is a conflict and you should know. The batch endpoint absorbs duplicates as success. Its caller is typically a worker resubmitting a whole job after a restart, and flipping a 500-item batch to failed because one key was already queued would defeat the point of having idempotency keys. The results[i].task you get back is the existing task, so your task mapping still resolves.

​
Matching results back to submissions

Two independent handles, and you want both:
​
integer
Positionally 1:1 with your input array. Use it to correlate the batch response with the tasks you sent.
​
string
Echoed back verbatim. Use it to correlate the webhook — which arrives minutes later, out of order, with no reference to your original array.
If you did not supply an idempotencyKey, the field is omitted from the task object rather than returned as null. Internally the task falls back to its own uuid as a key, which is unique by construction and therefore never dedupes.

​
Key lifetime

Keys on permanently retained tasks remain reserved after completion, failure, and the 24-hour public polling window. A polling 404 does not release the key. Use the same key for transport retries of one submission, and a new execution key (for example an added :r1 suffix) for a separate run. UUID format is not required. Records already moved to legacy history before permanent retention was enabled do not reserve keys retroactively.