List Workflow Runs
List workflow runs with page-number pagination or reliable completed-run cursor discovery.
pagination=cursor, the endpoint preserves its existing page-number response and created_at DESC order.
Authentication and scope
Cursor mode requires bothworkspaces-read and workflows-read. The token owner must be an administrator of the workflow workspace.
Cursor mode request
cursor.completed. Other statuses are rejected in cursor mode.created_at strictly greater than this activation boundary.meta.next_cursor. Do not decode or modify it.Cursor mode response
Cursor mode always excludes debug runs and incomplete runs. Results use the stable ordercompleted_at ASC, id ASC. The API holds back the current open second so no run can complete later behind an emitted checkpoint.
next_cursor is a durable checkpoint, including when has_more is false. Store it only after you have durably recorded every run on the page. The cursor contains the last (completed_at, id) position, encrypted and signed by the API.
Results advance strictly in completed_at ASC, id ASC order. Runs created after activation remain eligible until they complete, so a slow run appears on a later poll when its completion time moves beyond the stored checkpoint. Use only next_cursor as the client checkpoint and keep workflow_id:run_id:documentId as an idempotency key for client retries.
Activate without downloading history
- Send a bootstrap cursor request with
created_after=1970-01-01T00:00:00Zand ignore itsdata. - Store
meta.server_timeas the workflow’s immutableenabled_atvalue. - Store
meta.next_cursoras the initial checkpoint. - Use
created_after=enabled_atand the stored cursor for every later poll. The cursor accepts this one forward movement from the bootstrap boundary and skips the rest of the ignored history. - Follow pages while
has_more=true.
server_time before executing the bootstrap query. A run created before enabled_at stays excluded even if it finishes later. A run created after enabled_at remains eligible and appears when its status becomes completed, regardless of how long it takes.
Page-number compatibility
Whenpagination is omitted, the endpoint keeps the existing behavior:
- page-number pagination with 30 runs per page by default
- newest
created_atfirst - optional status filter
- optional
include_debug=1 - existing Laravel pagination metadata
Authorizations
Query Parameters
Set to cursor to activate cursor mode. Omit it to preserve page-number pagination.
cursor Page number in the existing page-number mode. Ignored in cursor mode.
x >= 1Required as completed in cursor mode. Other supported statuses remain available in page-number mode.
pending, running, paused, completed, failed, cancelled Required RFC 3339 activation boundary in cursor mode. Only runs with created_at strictly after this value are returned. It is immutable after the first cursor, except for the documented one-time transition from the epoch bootstrap boundary.
Opaque checkpoint returned in meta.next_cursor. Do not decode or modify it.
Include internal debug runs in page-number mode. Cursor mode always excludes them.
Number of runs per page. Defaults to 30 in page-number mode and 100 in cursor mode.
1 <= x <= 100