Skip to main content
Use the completed-run cursor API to copy workflow outputs into an external system without missing slow runs or downloading history from before activation.

​
Prerequisites

Create a dedicated API token with the minimum abilities:
  • workspaces-read
  • workflows-read
  • workflow-runs-output-read
  • documents-read
In the API token modal, the Raydocs Windows sync client preset selects exactly these abilities and scopes the token to the current workspace by default. The token owner must be an administrator of every workflow workspace the integration follows. Do not grant workflow-agent and do not send workflow-agent headers. Your workflow must finish with files.persistWorkspace. Its public output must expose the resulting documents array described in Get Workflow Run Output.

​
Activate a workflow feed

Send one bootstrap request in cursor mode. Ignore its runs, then store its meta.server_time as enabled_at and its meta.next_cursor as the initial cursor.
For every later poll, keep created_after equal to the stored enabled_at. This excludes runs created before activation while still discovering runs created after activation that take hours or days to complete.

​
Process one discovery page

For each returned run:
  1. Request the run’s public output.
  2. Validate that documents is an array and every entry contains documentId and filename.
  3. Build the idempotency key workflow_id:run_id:documentId.
  4. Store one download event per document.
  5. Commit the events and meta.next_cursor together.
  6. Request the next page when meta.has_more=true.
If one run has an invalid output, roll back the page and retry it later. A document download failure does not invalidate discovery; keep the event and retry the download independently. Follow pages while meta.has_more=true. After the last page, keep polling with its returned cursor; runs that complete later appear after the stored (completed_at, id) checkpoint.

​
Download a document

Request a fresh signed URL with the document’s documentId, then stream the response to a temporary local file.
Before exposing the final file, verify size and sha256 when present, flush the file to disk, and rename it atomically on the same volume. Request a new signed URL after expiration; never store a signed URL as durable state.

​
Reliability rules

  • Keep enabled_at immutable.
  • Treat the cursor as opaque.
  • Store the page cursor only after its events are durable.
  • Use the workflow_id:run_id:documentId idempotency key to absorb client or network retries safely.
  • Never advance past an invalid run output.
  • Never use temporary workflow fileRef download routes for persisted documents.