Operations

Every task submission returns a long-running operation. Store its ID beside your own job record; the operation is how you observe progress and retrieve the terminal response.

Understand the operation envelope

An operation is a common status envelope around a task-specific result:

{  "id": "op_01jexample000000000000000000",  "name": "accounts/acct_example/projects/project_example/operations/op_01jexample000000000000000000",  "ownerId": "acct_example",  "metadata": { "task": "atlasGenerate" },  "done": false,  "response": null,  "error": null,  "createdAtSecs": 1789412264,  "expiresAtSecs": 1789415864}

The API reference gives each task submission a type such as AtlasGenerateResponseOperation. This is not a second kind of operation. It means the common operation envelope above, with response typed as AtlasGenerateResponse. The generic GET /operations/{operation} endpoint can return work from any task, so its response type is simply Operation; use the task you submitted or metadata.task to interpret its successful response.

Submit once

Send a stable Idempotency-Key for each logical task. If a timeout or broken connection makes the response uncertain, retry the same validated body with the same key. Reusing that key with a different body returns 409.

curl --request POST "$WLT_API_BASE_URL/tasks:images2PosedRGBD" \  --header "WLT-Api-Key: $WLT_API_KEY" \  --header "Idempotency-Key: capture-job-4831" \  --header "Content-Type: application/json" \  --data @request.json

Do not create a new idempotency key for a transport retry; that can start duplicate work.

Wait or poll

For a bounded blocking read, call:

curl --request POST "$WLT_API_BASE_URL/operations/${WLT_OPERATION_ID}:wait" \  --header "WLT-Api-Key: $WLT_API_KEY" \  --header "Content-Type: application/json" \  --data '{ "timeoutSecs": 30 }'

Waiting is best-effort and capped server-side. The response may still have done: false. Poll with GET /operations/{operation} using capped exponential backoff and jitter when work outlives the wait.

Use done as the terminal signal:

• done: false: work is still running;
• done: true with response: the task succeeded;
• done: true with error: the task failed.

A fast task can come back from its submission already done: true with its response. The stored operation catches up a moment later, so a GET /operations/{operation} right after can still show done: false. Treat the first done: true you receive as final.

A response returned from the submission can carry each file the task produced inline, as a data URL in base64, and name each input it echoes back by assetId. images2PosedRGBD does this only when the request sets "base64Outputs": true; otherwise its submission response names files by assetId and url. The stored operation names the same files by assetId and url. Read a file from whichever form the response you hold carries.

Task metadata can report a phase or progress percentage, but clients must not infer completion from those fields.

List project operations

List entries include metadata, completion status, and failure details, but omit the task's response payload. Fetch GET /operations/{operation} for the result and output URLs; use done and error to distinguish success from failure in a list entry.

GET /operations lists the API key's project operations newest first. Use pageSize and preserve nextPageToken exactly. Filters are applied on the server, so a page holds only matching operations and paging stays exact at any volume:

task and status only search the last 30 days, even when createdAfter is earlier.

curl "$WLT_API_BASE_URL/operations?task=atlasGenerate&status=FAILED&createdAfter=1789344000&pageSize=50" \  --header "WLT-Api-Key: $WLT_API_KEY"

The authenticated platform shows the same history with the same filters on Operations.

Retention

An operation, its request trace, and its terminal response are available for 30 days after the operation is accepted. Do not plan on reading them later than that: record the operation ID, the request, and any output assets you need in your own systems within the window.

Output assets are kept in the project's library until you delete them, unless the account has chosen not to retain uploads and outputs (Account settings) or the request said so itself:

{ "prompt": "a cozy, sunlit living room", "purgeContentOnOperationCompletion": true }

Such an operation's outputs, and any input it consumed that was uploaded under the same setting, are purged one hour after it finishes; the operation's own record stays. Download what you need within that hour. The request field can turn purging on for one operation but cannot turn it off for an account that purges: sending false there is rejected. Where purging is not enabled, a request asking for it is refused with 412. Assets the platform will purge report "transient": true and no contentPath; read them through :createReadUrl.

Inspect a trace

GET /operations/{operation}:trace returns the request as you sent it beside the operation's response and error, served exactly as GET /operations/{operation} serves them. Use it to reproduce a result or compare the exact payload. A request recorded under an earlier version of the task's schema is returned as recorded. Like the operation itself, the trace is available while the operation is within the retention window.

Request cancellation

Cancellation is asynchronous and best-effort:

curl --request POST "$WLT_API_BASE_URL/operations/${WLT_OPERATION_ID}:cancel" \  --header "WLT-Api-Key: $WLT_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "requestId": "cancel-capture-job-4831",    "reason": "The input set was replaced."  }'

Reuse requestId when retrying cancellation. Continue polling until terminal; work that already finished may retain its real success or failure result.