Skip to main content
GET
List workflow definitions
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/workflows/list?limit=<1-100>&cursor=<opaque>[&lifecycle=][&tag=][&owningOrgUnitId=] Returns the workflows the caller may read, newest first, one page at a time.

Which workflows appear

Each workflow is decided at its own home org unit. The caller’s credential (an API key or an External App) must hold workflows:read there through its own role grants; a grant at a parent org unit covers the units beneath it. A workflow with no home, or one the caller cannot read, is left out of the page. Trashed workflows appear only with lifecycle=trashed.

Paging

Filters

Each filter is given at most once and is not empty; otherwise, or for an unknown lifecycle, 400 bad_request. Filters other than trashed apply after the page is read, so a filtered page can be shorter still: keep following meta.nextCursor. A page reads limit workflows and then omits the ones the caller cannot read, so it can be short or even empty while meta.hasMore is true. Keep following meta.nextCursor until hasMore is false; do not stop at an empty page. meta.nextCursor is null once there is nothing more.

Run counts

activeRuns and pendingApprovals count only the running runs the caller may read: the credential’s scopes must include runs:read, and its grants must hold runs:read at the run’s home org unit and at every company on the run. A run’s home is the org unit it recorded, or its workflow’s home when it recorded none (as an API- or Console-launched run does). A readable workflow can show 0 when none of its runs are readable. A page shares one bounded read of running runs across its workflows: each workflow counts at most 500, and fewer on a large page (a 100-row page counts at most 15 per workflow). A page also decides at most 50 distinct run home and company org units; a running run it cannot decide within that is not counted. When a workflow on the page has more running runs than it counted, or a run was left undecided, meta.partial is true and that page’s activeRuns and pendingApprovals are lower bounds, not totals. A smaller limit counts more per workflow.

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
default:25

Rows to read for this page, 1 to 100. A larger value is 400 too_big; zero, negative, fractional, non-numeric, empty or repeated values answer 400 bad_request.

Required range: 1 <= x <= 100
cursor
string

Opaque cursor: meta.nextCursor from the previous page.

lifecycle
enum<string>

Only workflows in this lifecycle. Omitted: live and retired workflows (trashed ones are listed only with trashed). Filters other than trashed apply after the page is read, so a page may be shorter still.

Available options:
live,
retired,
trashed
tag
string

Only workflows carrying this tag (case-insensitive).

Minimum string length: 1
owningOrgUnitId
string

Only workflows owned by this org unit. A repeated or empty filter, or an unknown lifecycle, answers 400 bad_request.

Minimum string length: 1

Response

Workflow 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.