Operation API

Operation API

Read asynchronous execution, inspect per-target failures, and cancel uncommitted work.

Operations use the shared execution lifecycle. Their result must be interpreted using the initiating feature's completion condition.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Read an operation

GET/organizations/{organization_id}/operations/{operation_id}
Scope
operations:read
Auth
Bearer API key

Returns type, target IDs, state, phase, timestamps, cancelability, errors, and target_results. Unknown or invisible IDs return 404; a missing operation does not imply success.

200Result

The response is similar to the following:

JSON
{
  "data": {
    "id": "op_001",
    "type": "endpoint.isolate",
    "state": "running",
    "cancelable": false,
    "target_results": [
      {
        "endpoint_id": "end_laptop01",
        "state": "pending",
        "error": null
      }
    ],
    "created_at": "2026-01-09T10:00:00Z",
    "finished_at": null
  },
  "request_id": "req_operation01"
}

List operations

GET/organizations/{organization_id}/operations
Scope
operations:read
Auth
Bearer API key

Lists visible operations. Use resource_id to reconcile an ambiguous mutation before creating replacement work. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
resource_idstringoptional

Find work related to a visible resource.

statestringoptional

Execution state.

one ofqueued, running, succeeded, failed, canceled, expired
200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Cancel an operation

POST/organizations/{organization_id}/operations/{operation_id}/cancel
Scope
operations:cancel
Auth
Bearer API key

Requests cancellation. Requires authority over the initiating resource as well as this scope. Send an empty object. Non-cancelable phases return 409 cancellation_unavailable.

202Accepted

Returns the current operation. Cancellation requests stop future cancelable work but do not reverse committed effects. Poll to a terminal state.