Skip to main content
GET
List Workflow Runs
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

pagination
string
required
Set to cursor.
status
string
required
Set to completed. Other statuses are rejected in cursor mode.
created_after
string
required
RFC 3339 timestamp. The API returns only runs with created_at strictly greater than this activation boundary.
cursor
string
Opaque checkpoint from the previous response’s meta.next_cursor. Do not decode or modify it.
per_page
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.

Authorizations

Authorization
string
header
required

Personal Access Token created from the Raydocs dashboard. Include in the Authorization header: Bearer <your_token> See API Keys for token creation and management.

Path Parameters

workspaceId
integer
required
workflowId
string<uuid>
required

Query Parameters

pagination
enum<string>

Set to cursor to activate cursor mode. Omit it to preserve page-number pagination.

Available options:
cursor
page
integer

Page number in the existing page-number mode. Ignored in cursor mode.

Required range: x >= 1
status
enum<string>

Required as completed in cursor mode. Other supported statuses remain available in page-number mode.

Available options:
pending,
running,
paused,
completed,
failed,
cancelled
created_after
string<date-time>

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.

cursor
string

Opaque checkpoint returned in meta.next_cursor. Do not decode or modify it.

include_debug
boolean

Include internal debug runs in page-number mode. Cursor mode always excludes them.

per_page
integer

Number of runs per page. Defaults to 30 in page-number mode and 100 in cursor mode.

Required range: 1 <= x <= 100

Response

Workflow runs

data
object[]
required
meta
object
required