Skip to main content
GET
List workflow runs
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/runs/list?limit=<1-100>&cursor=<opaque>&status=&workflowId=&kind=&versionId=&runType=&interfaceId= The list reaches every run you may read, wherever it was launched: the Forge Console, a schedule, a trigger, or any key or app. Every filter is optional and narrows it: Each filter may appear at most once. An unknown status, kind or runType, or an empty workflowId or versionId, answers 400; an id that names no run gives an empty page. limit defaults to 25, and a value above 100 is 400 too_big.

Paging

The list returns exactly the runs Get a run returns to you: you need runs:read at the run’s home (its own org unit, else its workflow’s owning org unit) and at every company it carries. A run with neither home is never listed. A page reads limit runs, then omits each run you may not read and each run a filter excludes, so a page can be short or empty while meta.hasMore is true. Keep following meta.nextCursor until hasMore is false; nextCursor is null once there is nothing more. Treat the cursor as opaque: one the list did not issue is a 400 “Invalid cursor” naming the cursor field. meta.partial is true when the read stopped deciding runs at its limits (a page whose runs span many org units and companies); that page may omit runs you may read, and meta.nextCursor still moves past them. To see them, request the same page again (the cursor you sent for it) with a smaller limit.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

limit
integer
Required range: 1 <= x <= 100
cursor
string
runType
string
interfaceId
string

Only runs launched through this interface. Send your own to list only the runs you launched.

status
enum<string>

Only runs with this status. running lists the active runs.

Available options:
running,
completed,
failed,
cancelled,
cancellation_requested,
paused
workflowId
string

Only runs of this workflow.

Minimum string length: 1
kind
enum<string>

Only production runs or only test runs.

Available options:
production,
test
versionId
string

Only runs of this workflow version.

Minimum string length: 1

Response

Run list

data
object[]
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.