POST /api/instances

Start a new process instance (omit version to use latest)

Requires the operate permission (or admin).

Request

{
  "process": "order_pipeline",
  "version": 1,
  "input": {
    "order_id": 42
  }
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "process": "order_pipeline",
  "version": 1,
  "status": "running"
}

Fails with 400, 404, 500.

GET /api/instances

List process instances - roots only unless children=true, so one row per tree

Requires the read permission (or admin).

Parameter	In	Description
status	query	Filter by status, or several comma-separated (running,paused) — the grammar genctl upgrade —status takes. The enum is the vocabulary; a comma-separated list of those values is accepted. One of running, pausing, paused, failing, cancelling, completed, failed, raised, cancelled.
phase	query	Filter by why a running instance is not executing a task. The three are not one kind of thing: children (blocked until its children settle), collecting (children terminal, their outputs still to merge — runnable now), external (parked until someone answers, or until its timeout). Orthogonal to status — all three are still running, and survive a pause
task	query	Filter by the exact task id the instance sits on — where it is running, parked, or where it stopped. A task id is unique only within its definition, so pair it with process to mean one task
error_code	query	Filter by exact error code. Authored codes (from a raise or panic clause) are lower_snake_case; engine-produced codes contain a dot, e.g. http.500, pre.timeout, engine.spawn.
process	query	Filter by exact process name, across every version
version	query	Filter by exact process version (0 = any)
children	query	Include child instances. Omitted, the listing is ROOTS ONLY - one row per tree, which is the unit an upgrade or a pause acts on; a child_list fan-out would otherwise bury the roots it belongs to. Every row carries parent_id, so the two are still told apart when children are included
created_after	query	Only instances created at/after this unix-millis timestamp
created_before	query	Only instances created strictly before this unix-millis timestamp
updated_after	query	Only instances updated at/after this unix-millis timestamp
updated_before	query	Only instances updated strictly before this unix-millis timestamp
sort	query	Sort key (per-endpoint whitelist; omit for the default)
order	query	Sort direction (omit for the endpoint default). One of asc, desc.
limit	query	Page size (default 20, cap 100)
after	query	Cursor from a previous page’s page.next_cursor — fetch the next page
before	query	Cursor from a previous page’s page.previous_cursor — fetch the previous page

Response

{
  "items": null,
  "page": {
    "size": 0,
    "items_before": 0,
    "items_after": 0,
    "sort": "",
    "order": ""
  }
}

Fails with 400, 500.

GET /api/instances/{id}/detail

Get everything stored on a process instance: its state verbatim, plus the columns around it

Requires the read permission (or admin).

Parameter	In	Description
resolve	query	Splice externalized values into the state where they fit; anything over the per-object limit stays listed under objects for the caller to fetch
id	path	The instance id

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "process": "order_pipeline",
  "version": 1,
  "status": "running",
  "task": "charge_card",
  "retry_count": 0,
  "created_at": "",
  "updated_at": "",
  "state": {
    "_children": {
      "charge_card": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0"
    },
    "input": {
      "order_id": 42
    },
    "outputs": {
      "reserve": {
        "ok": true
      }
    }
  },
  "lease_epoch": 0,
  "task_epoch": 3,
  "parent_task_epoch": 0,
  "next_replayable": false,
  "external_claim_epoch": 0,
  "objects": [
    {
      "path": [
        "state",
        "outputs",
        "render"
      ],
      "ref": "9f2ac1b4e7d05f38",
      "size": 221110
    }
  ]
}

Fails with 400, 404, 500.

GET /api/instances/{id}

Get status of a process instance

Requires the read permission (or admin).

Parameter	In	Description
id	path	The instance id

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "process": "order_pipeline",
  "version": 1,
  "status": "failed",
  "task": "charge_card",
  "retry_count": 0,
  "error_code": "only_once.interrupted",
  "error_message": "the task may have already run",
  "output": {
    "shipped": true
  },
  "created_at": "",
  "updated_at": ""
}

Fails with 400, 404, 500.

GET /api/instances/{id}/logs

Get the execution audit trail for a process instance (newest first) - the whole tree when the id names a root, unless flat=true

Requires the read permission (or admin).

Parameter	In	Description
level	query	Lowest level to return: this level and everything above it (warn keeps errors). One of debug, info, warn, error.
created_after	query	Only logs at/after this unix-millis timestamp
created_before	query	Only logs strictly before this unix-millis timestamp
flat	query	This instance’s own rows only. Without it a ROOT id answers with every row in its tree, which is one indexed read rather than a walk; a child id answers with its own rows either way, since a tree is addressed by its root
sort	query	Sort key (per-endpoint whitelist; omit for the default)
order	query	Sort direction (omit for the endpoint default). One of asc, desc.
limit	query	Page size (default 20, cap 100)
after	query	Cursor from a previous page’s page.next_cursor — fetch the next page
before	query	Cursor from a previous page’s page.previous_cursor — fetch the previous page
id	path	The instance id

Response

{
  "items": null,
  "page": {
    "size": 0,
    "items_before": 0,
    "items_after": 0,
    "sort": "",
    "order": ""
  }
}

Fails with 400, 404, 500.

POST /api/instances/{id}/pause

Pause a running root process instance and its entire descendant tree; takes effect at the next task boundary, so a task already executing runs to completion. An assertion: 200 if the tree stopped, 202 if a task already in flight is still draining, 204 if it was not running anyway

Requires the operate permission (or admin).

Parameter	In	Description
id	path	The root instance’s id; the call acts on its whole tree and refuses a child

Response

{
  "outcome": "",
  "status": "",
  "instances": 0
}

Fails with 400, 404, 500.

POST /api/instances/{id}/resume

Resume a paused root process instance and its tree, continuing exactly where it stopped (timers kept running while paused). An assertion: 200 if it was resumed, 204 if the tree was already advancing; 409 only if it has settled and cannot advance again

Requires the operate permission (or admin).

Parameter	In	Description
id	path	The root instance’s id; the call acts on its whole tree and refuses a child

Response

{
  "outcome": "",
  "status": "",
  "instances": 0
}

Fails with 400, 404, 409, 500.

POST /api/instances/{id}/cancel

Stop a root process instance and its entire descendant tree for good. Terminal and irreversible — unlike pause there is no way back, and a cancelled instance is not retryable. Takes effect at the next task boundary, so a task already executing runs to completion; a claimed external task is told to stop on its next renewal. An assertion: 200 if the tree stopped, 202 if a task already in flight is still draining, 204 if there was nothing live to stop

Requires the operate permission (or admin).

Parameter	In	Description
id	path	The root instance’s id; the call acts on its whole tree and refuses a child

Response

{
  "outcome": "",
  "status": "",
  "instances": 0
}

Fails with 400, 404, 500.

POST /api/instances/{id}/retry

Retry a failed root process instance, reviving its tree where it died and granting the failing task another attempt beyond its on_error budget

Requires the operate permission (or admin).

Parameter	In	Description
force	query	Override only_once retry protection
id	path	The root instance’s id; the call acts on its whole tree and refuses a child

Response

{
  "outcome": "",
  "status": "",
  "instances": 0
}

Fails with 400, 404, 409, 500.

POST /api/instances/{id}/upgrade

Move a process instance and every live descendant to another version of their definitions

Requires the deploy permission (or admin).

Parameter	In	Description
id	path	The root instance’s id; the call acts on its whole tree and refuses a child

Request

{
  "from_version": 0,
  "to_version": 0
}

Response

{
  "upgraded": false,
  "moves": null
}

Fails with 400, 404, 409, 500.