Runs
List workflow runs
Returns the runs you may read, each decided at its home and companies, one page at a time. Requires permission runs:read.
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 needruns: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.

