Jobs, operations and recovery

The central service owns durable work. Studio, REST, Python and MCP observe the same engineering lifecycle. Closing a browser/chat or timing out a client wait does not cancel accepted work.

Compute jobs

Geometry, mesh, simulation and prediction submissions normally return HTTP 202 and a job id. Follow GET /v1/jobs/{id} or get_job; use job events for incremental evidence.

State

Meaning

Next action

queued

Accepted, waiting for admission/resources

Poll; read the queue explanation

submitting

Submission is in progress

Retain this identity and wait

submission_unknown

Acknowledgement/outcome is uncertain

Reconcile the existing job; do not create another

running

Work has been dispatched; resource waits can still be reported

Follow progress and queue metadata

awaiting_decision

Verified mesh candidate missed its requested cell range

Review count/quality and accept or discard explicitly

cancelling

Cancellation requested, not yet confirmed

Keep observing; work may still be running

cancelled

Cancellation confirmed

Inspect retained records as needed

failed

Terminal failure

Read error stage, events and available diagnostics

succeeded

Execution completed

Inspect quality/convergence and the actual outputs

Some listings also expose a Status unavailable presentation/filter. It describes uncertain status; it is not evidence that new compute is required.

Preparation operations

Attachment import, geometry inspection and viewer preparation can return operation_id, status_url, cancel_url and retry_after_seconds. REST callers should request Prefer: respond-async on supported preparations. MCP handles this automatically for the relevant tools.

Follow GET /v1/operations/{id} / get_operation until succeeded, failed or cancelled; on success continue from result. Retain operation IDs across reconnects. Canceling a preparation does not cancel its source simulation or mesh.

Idempotency

REST job submissions carry Idempotency-Key. MCP submission tools carry idempotency_key. Use a fresh key for a newly intended job, even if its settings match an earlier job. Reuse the original key only when retrying/reconciling that same request. A changed body with the same identity can be rejected as a conflict.

An HTTP read error, client timeout or lost acknowledgement is not permission to launch another job. Poll/reconcile the saved identity first. New engineering attempts after quality, resource or count failures must follow the retry allowance and review policy.

Review and cancellation

POST /v1/jobs/{id}/review / review_job accepts action="accept" or "discard" and a reason. Neither starts compute. An accepted candidate becomes eligible for downstream use; a pending candidate is not.

Use POST /v1/jobs/{id}/cancel / cancel_job for explicit compute cancellation. Deleting a finished job from workspace history is different from cancellation and does not erase billing history or necessarily delete retained artifacts.

Workspace history

list_jobs can work without a project. Filter by kind, state, entry point, user/credential, date and search text as permitted. Follow next_cursor using after. list_activity combines jobs, preparations and recorded engineering calls; get_workflow supplies continuation context. Historical synchronous calls are not necessarily backfilled.