An operation records the outcome of work on a workspace, computer, database or checkpoint. An idempotency key identifies a request you may need to repeat. See Track and wait for operations for CLI steps.
Operation states
| State | Meaning |
|---|---|
running | The operation has not reached an outcome. |
finished | The operation succeeded. This state is terminal. |
failed | The operation failed. Its error gives a code, message and details. This state is terminal. |
resource identifies the affected resource. For a branch or checkpoint restore,
it identifies the new computer or database. The resource's own state, pending
and error describe its current condition; an operation describes the work that
started it or changed it.
Keep the returned operation ID, or find it with
List operations. A resource read can return
operations: [] while earlier work is still running. Use
Get operation to read that work's outcome.
For MCP call budgets and outcome results, see MCP waiting behavior.
Which requests return operations
These are the current behaviors for successful requests. HTTP status alone does not establish whether the work is still running.
| Action | Operation behavior |
|---|---|
| Create or branch a computer or database; restore a computer checkpoint | Returns an operation. HTTP 200 when it has reached a terminal state, including failure; HTTP 202 while creation continues. |
| Create a computer checkpoint | HTTP 201 with a checkpoint creation operation. |
| Delete a computer, database or checkpoint | HTTP 202 with a deletion operation. For an already deleting checkpoint, a repeat returns its running operation or an empty list if none is running. |
| Delete a workspace | HTTP 202 with an operation already finished. |
| Sleep or wake a computer or database | HTTP 200. Returns an operation only if the API's bounded wait runs out; otherwise operations: []. An idle resource already in the requested state also returns an empty list. |
| Create a workspace or add a member | HTTP 201 with operations: []. |
| Update computer, database or workspace settings; change or remove a member | HTTP 200 with operations: []. |
| Exec | No operation. JSON responses have operations: []; streaming responses carry output and an exit or error event. |
Unsupported actions, including computer restart and database creation from a checkpoint, return an error before starting an operation.
The API reference owns request and response details: computer creation, checkpoint creation, sleep, and workspace deletion.
Waiting and conflicts
Waiting polls an existing operation. Stopping the CLI wait or reaching its timeout does not cancel the operation. A failed operation stays failed; waiting again does not retry the action.
The worker has a separate deadline for computer, database and checkpoint operations: 15 minutes by default. Expiry marks the operation failed; it does not undo the work or delete a resource that was created.
Some lifecycle actions refuse to proceed while an operation runs on the resource.
423 operation_in_progress includes details.operation_id and Retry-After: 5.
Wait for that operation, then reconsider the action. A resource with a pending
transition can instead return 409 invalid_state. This is not a blanket lock on
all mutations; live settings updates have their own checks.
Listing operations requires access to the workspace. Reading one by ID also allows the principal who started it, even after workspace deletion. See Workspace permissions.
Idempotency
Replay support depends on the action:
| Action | Idempotency-Key behavior |
|---|---|
| Create a computer, database, computer checkpoint or workspace; add a member | Required; replays a stored response. |
| Branch a computer or database; restore a computer checkpoint | Optional; replays a stored response when supplied. |
| Settings updates, member changes/removal, deletes, sleep, wake and exec | Accepted but not replayed. Repeating exec runs the command again if its state checks pass. |
The CLI supplies a key for commands that require one. Those commands accept
--idempotency-key; without it, each invocation gets a new key. CLI branch and
restore commands do not expose this flag or send a key.
Keys contain 1–255 characters and belong to the authenticated principal, across
workspaces and routes. The API retains a stored response for 24 hours. A retry
must use the same method, path and validated request body. JSON object key order
does not matter. Reusing a stored key for a different request returns
409 idempotency_conflict.
A replay returns the stored status and body, including the original operation IDs.
It does not refresh resource state or rerun a failed operation. Database creation
is an exception to an unchanged body: replays return connection.password and
connection.uri as null. Retrieve them through
Get connection.
Authentication, authorization and some resource checks run before replay. A changed source state or lost access can therefore prevent a retry from reaching the stored response.
The API stores a response after the handler completes. It does not store thrown errors or combine simultaneous requests with the same key. A lost response does not prove that no work started. After a key expires, reusing it can start new work.
X-Request-ID identifies the current HTTP request for diagnosis and matches
error.request_id on failures. It does not replace an operation ID or an
idempotency key.