Skip to main content
Use cursor mode for integrations that must discover every completed run, including runs that finish long after they were created. If you omit pagination=cursor, the endpoint preserves its existing page-number response and created_at DESC order.

​
Authentication and scope

Cursor mode requires both workspaces-read and workflows-read. The token owner must be an administrator of the workflow workspace.

​
Cursor mode request

​
string
required
Set to cursor.
​
string
required
Set to completed. Other statuses are rejected in cursor mode.
​
string
required
RFC 3339 timestamp. The API returns only runs with created_at strictly greater than this activation boundary.
​
string
Opaque checkpoint from the previous response’s meta.next_cursor. Do not decode or modify it.
​
integer
default:"100"
Number of runs to return, from 1 to 100.

​
Cursor mode response

Cursor mode always excludes debug runs and incomplete runs. Results use the stable order completed_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.
Keep created_after fixed to the workflow activation time. Direct activation boundaries are locked by the first cursor. Do not replace the boundary with the last run’s creation or completion time.

​
Activate without downloading history

  1. Send a bootstrap cursor request with created_after=1970-01-01T00:00:00Z and ignore its data.
  2. Store meta.server_time as the workflow’s immutable enabled_at value.
  3. Store meta.next_cursor as the initial checkpoint.
  4. Use created_after=enabled_at and 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.
  5. Follow pages while has_more=true.
The API chooses a conservative closed whole-second 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

When pagination is omitted, the endpoint keeps the existing behavior:
  • page-number pagination with 30 runs per page by default
  • newest created_at first
  • optional status filter
  • optional include_debug=1
  • existing Laravel pagination metadata
Cursor-only fields do not appear in the page-number response.

​
Filter by caller or metadata

Both pagination modes accept api_token_id, root_run_id and a metadata object encoded as query parameters. Criteria combine with AND and metadata uses exact string matches. Query strings must be URL-encoded.
api_token_id filters the direct caller. Use root_run_id to discover the initial run and its descendants within the selected workflow. The endpoint never expands the caller’s workspace or workflow permissions. Keep every filter unchanged while following a cursor. The checkpoint binds normalized filters; changing, adding or removing a filter returns 422. Start without a cursor for a new search. Older unfiltered cursors remain supported for unfiltered requests. Summaries expose caller provenance and run metadata without embedding exact inputs. Metadata references can match several attempts; they are not unique or idempotency keys. Filtering arbitrary input fields is not supported.