Lifecycle
Get operation
Poll an asynchronous start or stop.
GET
Get computer operation
Use the
poll_url returned by an asynchronous start or stop, or by the restart of a dedicated GPU computer. Authenticate each poll with the same API key.
The response contains id, desktop_id (the computer UUID), action (start, stop, restore for an in-place restore from a backup, or clear_restart for the restart of a dedicated GPU computer), status, result, error, created_at, updated_at, and poll_url.
status is queued, running, succeeded, failed, or needs_review. Poll every two seconds while queued or running; the response carries Retry-After: 2. A successful operation has a result such as { "success": true }; failed operations have an error containing error, code, and status, plus retry_after (seconds) when it says when to try again.
needs_review means the host’s answer was lost and the result is uncertain. Orgo checks the computer and settles the operation as succeeded or failed on its own, within about two hours at most. One it settles as failed carries code OPERATION_NOT_COMPLETED, or OPERATION_UNRESOLVED when the computer could not be checked within the two hours. A second start or stop returns 409 until then, to avoid repeating an action that may already have completed.
Operations are scoped to their computer and workspace. A missing or invalid API key returns 401 with { "error": "Authentication required" } or { "error": "Invalid API key" }. An unknown operation, an operationId that is not a UUID, or one belonging to another computer returns 404 with { "error": "Operation not found" }. An unknown computer returns 404 with { "error": "Computer not found (computer_not_found).", "code": "computer_not_found" } to a key, or { "error": "Desktop not found" } signed in with a session, and a workspace you cannot access returns 403. A key refused before the poll runs, such as a restricted key without Computers read (key_permission) or a computer’s own key (computer_key), returns the codes in Codes any endpoint can return to a key. A Can chat member is also refused with 403 and { "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only).", "code": "workspace_read_only" }: polling an operation counts as a write in the access check. Over the workspace owner’s plan rate limit for other API calls, a poll returns 429 with code rate_limited, limit: "api_other_per_minute" and a Retry-After header with the seconds to wait, described in Plan rate limits. A trial computer whose trial has ended returns 402 with { "error": "Choose a plan to continue." }. A computer paid by its own subscription or reservation whose payment has lapsed returns 402 with { "error": "Manage this computer’s payment in Account → Usage." }. If Orgo cannot verify the credential because of a server-side fault, such as a database outage, the poll returns 503 with { "error": "Service temporarily unavailable. …" } and Retry-After: 5. Retry after that delay; do not rotate the key.Authorizations
Response
Operation state.