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 only when at least one followed workflow exposes a persisted documentRef
In the API token modal, the Raydocs Windows sync client preset includes documents-read so it supports both output types 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. The public output must expose the documents array described in Get Workflow Run Output. Each item may be a persisted documentRef or a temporary workflow-run fileRef with its SHA-256. Use a fileRef when external delivery happens promptly (for example, the standard CDJ Connect ZIP); use files.persistWorkspace only when a durable workspace document is also needed.

​
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 has a supported type, filename, non-negative size, and a 64-character hexadecimal sha256.
  3. For a documentRef, validate documentId and matching workspaceId; for a fileRef, validate id.
  4. Build the idempotency key workflow_id:run_id:type:source_id.
  5. Store one download event per output file.
  6. Commit the events and meta.next_cursor together.
  7. 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 an output file

Request a fresh signed URL with the document’s documentId, then stream the response to a temporary local file.
For a temporary fileRef, request the workflow-run file URL instead:
Before exposing the final file, verify size and sha256, 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:type:source_id idempotency key to absorb client or network retries safely.
  • Never advance past an invalid run output.
  • Request the correct route for the output type: document URL for a documentRef; run-file URL for a fileRef.
  • A run fileRef is temporary. Download it promptly and do not use it as a durable workspace document identifier.