Wait for an operation to reach a terminal state

Long-polls server-side until the operation reaches a terminal state (SUCCEEDED, FAILED, CANCELLED) or the timeout elapses. Returns the latest Operation either way — check done to distinguish.

Server-side this is a live subscription on the operation row, not a polling loop, so the response fires within milliseconds of the workflow reaching its terminal state.

State for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (done: true) is immutable.

POST /operations/{id}:wait

Wait for an operation to reach a terminal state

cURL

curl --request POST \
  --url https://api.akua.dev/v1/operations/{id}:wait \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "<string>",
  "workspace_id": "<string>",
  "organization_id": "<string>",
  "owner_id": "<string>",
  "parent_operation_id": "<string>",
  "done": true,
  "html_url": "https://app.akua.dev/dashboard/installs/inst_j572abc...?tab=operations",
  "metadata": {
    "cluster_id": "<string>"
  },
  "response": {
    "cluster_id": "<string>"
  },
  "error": {
    "message": "<string>"
  },
  "last_error": {
    "message": "<string>",
    "step_name": "<string>"
  },
  "started_at": 1,
  "completed_at": 1,
  "steps": [
    {
      "name": "<string>",
      "started_at": 1,
      "completed_at": 1,
      "error_message": "<string>",
      "retryable": true,
      "skippable": true
    }
  ]
}

Authorizations

Authorization · string · header · required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Path Parameters

id · string · required

Operation ID. Prefixed form op_<id> is canonical; bare IDs accepted during transition.

Required string length: 1 - 53

Example:

"op_j572abc..."

Query Parameters

timeout · integer

Max seconds to wait for the operation to reach a terminal state. Default 30, max 60.

Required range: 1 <= x <= 60

Response

200

application/json

Operation in its latest known state (terminal or still running on timeout)

id · string · required

Required string length: 1 - 53

workspace_id · string | null · required

Required string length: 1 - 53

organization_id · string | null · required

Required string length: 1 - 54

owner_type · enum<string> · required

Domain entity collection the operation acts on.

Available options: install, repository_change_request, repository, workspace, machine, cluster, package

owner_id · string · required

Prefixed ID of the entity this operation acts on. Prefix matches owner_type (ws_, mch_, clu_, pkg_, inst_, rcr_, repo_).

parent_operation_id · string | null · required

ID of the chained parent operation, when present.

Required string length: 1 - 53

state · enum<string> · required

Lifecycle state. Past-participle terminal states per AIP-216.

Available options: RUNNING, SUCCEEDED, FAILED, CANCELLED

done · boolean · required

True iff state is a terminal value.

html_url · string<uri> · required

Deep link to the dashboard view of this operation.

Example:

"https://app.akua.dev/dashboard/installs/inst_j572abc...?tab=operations"

metadata · object · required

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Option 15

Option 16

Option 17

Option 18

Option 19

Option 20

Option 21

Option 22

Option 23

Option 24

Option 25

Option 26

Option 27

Show child attributes

response · object · required

Populated only when done && state === "SUCCEEDED". Discriminated by type.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Option 15

Option 16

Option 17

Option 18

Option 19

Option 20

Option 21

Option 22

Option 23

Option 24

Option 25

Option 26

Option 27

Show child attributes

error · object · required

Populated when state is FAILED or CANCELLED.

Show child attributes

last_error · object · required

Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry.

Show child attributes

started_at · integer · required

Unix timestamp (seconds)

Required range: x >= 0

completed_at · integer | null · required

Unix timestamp (seconds)

Required range: x >= 0

steps · object[]

Show child attributes