List processes

Returns process snapshots filtered by optional ref, state, and status query parameters. The status filter accepts the terminal exit states (success, failed, timeout, canceled) or ‘null’ to match processes that have not finished.

GET /processes

List processes

cURL

curl --request GET \
  --url http://localhost:9371/processes

200

{
  "items": [
    {
      "id": 1,
      "pid": 1,
      "state": "queued",
      "exitState": "failed",
      "error": "<string>",
      "createdAt": "<string>",
      "completedAt": "<string>",
      "ref": "<string>"
    }
  ],
  "nextCursor": "<string>",
  "hasMore": true
}

Query Parameters

ref · string

Optional reference string used to filter processes.

state · enum<string>

Current lifecycle state of a process.

Available options: queued, running, idle, terminating

status · enum<string>

Filter processes by terminal exit state. Use 'null' to match processes that have not finished.

Available options: failed, success, timeout, canceled, null

cursor · string

Opaque pagination token returned as nextCursor by the previous response. Pass it back unchanged to fetch the next page; null/omitted fetches the first page. Cursors encode position, not filters, so change filters only between pages when starting over.

Maximum string length: 2048

limit · integer · default: 20

Maximum number of items per page. Clamped to a maximum of 100; defaults to 20.

Required range: 1 <= x <= 100

Response

200

application/json

Matching processes.

Paginated collection envelope.

items · object[] · required

Processes that match the provided query filters.

Show child attributes

nextCursor · string | null · required

Opaque cursor for the next page; null when there are no more items. Echo it back as the cursor query parameter to continue paginating.

hasMore · boolean · required

Whether additional pages exist. When true, nextCursor is a valid cursor; when false, pagination has reached the end.