Read durable Run state

GET

/v1/sessions/{sessionId}/runs/{runId}

const url = 'https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/runs/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/runs/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731 \
  --header 'Authorization: Bearer <token>'

Requires wamp.cloud.sessions:read. The Run id is the Turn id that created it, so you never have to discover one. status is durable server truth and moves queued → dispatching → running, then either to a terminal completed/failed/cancelled/crashed or to awaiting, which means the agent has asked a question and will not proceed until a Turn answers it. attempts counts dispatch attempts, so a value above 1 is a recovered handoff rather than repeated agent work, and cancellationRequested records that a cancel command was accepted even while the status is still running. lastError.code is a stable machine code and is the only failure detail exposed here.

Authorizations

cloudInstallationBearer

Parameters

Path Parameters

sessionId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

A UUID you mint and own; it is the idempotency key for creation and the address of every Turn, artifact and publication underneath

runId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

The Run UUID, which is the same value as the id of the Turn that created it

Responses

200

Run

application/json

object

run

required

One durable execution attempt-set for a Turn. Exactly one Run exists per Turn, it survives worker loss and sandbox replacement, and only one Run per Session may be active at a time.

object

required

Run id, always equal to the id of the Turn that created it

string format: uuid

sessionId

required

Session this Run belongs to

string format: uuid

status

required

queued, dispatching and running are in flight, awaiting means the agent is blocked on human input, and completed, failed, cancelled and crashed are terminal

string

Allowed values: queued dispatching running awaiting completed failed cancelled crashed

attempts

required

How many times a worker has claimed this Run; recovery after a lost worker increments it instead of creating a second Run

integer

cancellationRequested

required

Whether cancellation was durably requested; it stays true after the Run terminates, and it never asserts that an external side effect was undone

boolean

lastError

Coarse machine code for the most recent failure, retained across retries; absent when nothing has failed

object

code

required

string

createdAt

required

When admission committed this Run in queued

string format: date-time

updatedAt

required

Last durable Run state change

string format: date-time

startedAt

When a worker actually began executing; absent while the Run is still queued

string format: date-time

completedAt

When the Run reached a terminal status; absent otherwise

string format: date-time

Example

{
  "run": {
    "id": "c47a1e08-3d6b-4a92-9f15-8b70d2e5c6a4",
    "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "status": "completed",
    "attempts": 1,
    "cancellationRequested": false,
    "createdAt": "2026-08-12T09:20:31Z",
    "updatedAt": "2026-08-12T09:44:02Z",
    "startedAt": "2026-08-12T09:21:07Z",
    "completedAt": "2026-08-12T09:44:02Z"
  }
}

404

The resource is missing or inaccessible

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_session_not_found"
}