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 |
|---|---|---|
|
Accepted, waiting for admission/resources |
Poll; read the queue explanation |
|
Submission is in progress |
Retain this identity and wait |
|
Acknowledgement/outcome is uncertain |
Reconcile the existing job; do not create another |
|
Work has been dispatched; resource waits can still be reported |
Follow progress and queue metadata |
|
Verified mesh candidate missed its requested cell range |
Review count/quality and accept or discard explicitly |
|
Cancellation requested, not yet confirmed |
Keep observing; work may still be running |
|
Cancellation confirmed |
Inspect retained records as needed |
|
Terminal failure |
Read error stage, events and available diagnostics |
|
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.