Operation API
Read execution state, poll outcomes, inspect child operations, and cancel work.
The Operation API reports execution progress for accepted infrastructure changes. Operations are organization-scoped and filtered by the caller's resource access.
Read an operation
/organizations/{organization_id}/operations/{operation_id}Returns the current execution record. Reading does not restart work or extend its lifetime.
The response distinguishes execution state from its phase:
{
"data": {
"id": "op_create01",
"type": "droplet.create",
"state": "running",
"phase": "starting_guest",
"resource_ids": ["drp_web01", "vol_root01"],
"child_operation_ids": [],
"cancelable": true,
"created_at": "2025-12-16T10:00:00Z",
"started_at": "2025-12-16T10:00:01Z",
"finished_at": null,
"error": null
},
"request_id": "req_poll01"
}The operation fields describe progress, ownership, cancellation, and failure:
| Field | Type | Behavior |
|---|---|---|
state | String | queued, running, reconciling, canceling, succeeded, failed, or canceled |
phase | String or null | Feature-specific active stage; clients must tolerate new values |
resource_ids | String array | Resources affected or created by the operation |
child_operation_ids | String array | Execution children for plans and bulk actions |
cancelable | Boolean | Whether the active phase permits cancellation |
finished_at | Timestamp or null | Set after a terminal result |
error | Object or null | Code, message, details, and retryability after failure |
progress | Object or omitted | Phase-specific counters; not a completion-time guarantee |
A 404 can mean an unknown ID, expired retained history, or an operation outside
the account's visible scope. It must not be treated as success.
List operations
/organizations/{organization_id}/operationsLists operations visible to the caller using the selected filters.
Supports project_id,
resource_id, state, and type filters plus standard pagination. It requires
operations:read and returns only permitted records.
Use resource_id to find the operation holding a lock after a client loses
its original response. Use the original idempotency key when retrying the
mutation rather than guessing whether a missing response means no work occurred.
Polling
After 202, read the returned operation until it reaches succeeded, failed,
or canceled. Respect a response's Retry-After and increase delay during long
operations. A client-side deadline stops waiting; it does not cancel the operation.
A successful parent result must still be interpreted according to its type. Maintenance results include skipped targets and child outcomes. Inspect resource health and application readiness after the infrastructure result.
Cancel
/organizations/{organization_id}/operations/{operation_id}/cancelRequests cancellation of a cancelable operation.
Send an empty JSON object. The operation must report cancelable=true.
The response is 202 with the operation summary in canceling or its observed
terminal state if work finished during the request.
A non-cancelable phase returns 409 cancellation_unavailable. A cancellation
request does not reverse committed changes. Poll until a terminal result and
inspect completed steps and retained resources.
Error recovery
A failure's retryable value identifies whether repeating the intended operation
can be appropriate after the reported condition clears. It is not permission
to start an unlimited retry loop. Reconcile current resource state first.
Use Operations for locks and partial changes, API conventions for request retries, and Webhooks for asynchronous completion notifications.