Test a whole workflow

POST /{workflowId}/test needs workflowBuilder.

What this endpoint does

Walks the workflow from its trigger and returns one trace entry per step it reached, in execution order. mode decides whether the real step services run:

mode: "live" is the default and behaves like a triggered run: every step executes for real, in order, and may write, send, call outside or pay a reward.

mode: "dry-run" is opt-in and side-effect free: read-only steps really run, and every step that would write, send or call is simulated with the inputs it would have used.

A trace shows which branch the run took, or would take. That is the part no single step test can answer.

Quick start

Authentication and permission

Authorization: Bearer <API_KEY> with workflowBuilder, on a workflow of the key's community. One permission covers both modes; there is no separate live-test permission and no confirmation header, so mode is the only thing that decides whether the walk costs anything.

The workflow must have a trigger, because the walk starts from its output. A single-step test does not have that requirement.

Failure	Meaning	Recovery
`400 VALIDATION_FAILED`	The workflow has no trigger	`PUT /{workflowId}/trigger` first.
`404 WORKFLOW_NOT_FOUND`	Unknown id, or another community's workflow	Use an id from this community.

Complete examples

A dry run seeded with a synthetic event:

A live run, which is what an omitted mode gives you: it behaves like a real run of the workflow:

A dry run that takes the condition branch: the read step executed, the write step was simulated, and the other branch was skipped.

{
  "data": {
    "mode": "dry-run",
    "sideEffects": "none",
    "workflowId": "65f1a2b3c4d5e6f708192a3b",
    "status": "success",
    "trace": [
      { "nodeId": "65f1a2b3c4d5e6f708192a3c", "name": "Read member XP", "type": "platform-action", "status": "executed", "output": { "XP": 150 }, "warnings": [] },
      { "nodeId": "65f1a2b3c4d5e6f708192a3e", "name": "XP over 100?", "type": "router", "status": "executed", "warnings": [] },
      { "nodeId": "65f1a2b3c4d5e6f708192a3d", "name": "Add 10 XP", "type": "platform-action", "branch": "XP > 100", "branchIndex": 1, "status": "simulated", "wouldDo": { "action": "post-user-fields" }, "warnings": [] },
      { "nodeId": "65f1a2b3c4d5e6f708192a3f", "name": "Notify receiver", "type": "http", "branch": "Otherwise", "branchIndex": 2, "status": "skipped", "warnings": [] }
    ],
    "redactedPaths": []
  }
}

Success and readback

HTTP 200 with mode, sideEffects, status (success when no step failed, fail otherwise), trace and redactedPaths.

Each trace entry carries the step id, name and type, its status, and for a step inside a router the branch name and its branchIndex. branchIndex in a trace is 1-based, matching the router result the canvas shows: the first branch is 1. The write side counts from zero instead, so position.branchIndex and the branches/{branchIndex} path name the first branch as 0. A step on a branch the run did not take is skipped, which is how a trace proves the branch decision.

A live test also returns historyId: the transient record the live run produced. The platform removes that record after the call, so it is an identifier for the run you just caused, not a history entry to read back.

For a dry run, prove nothing changed with a read on the data the workflow would touch: the member's field value, or the last run in GET /{workflowId}/runs, must be the same before and after.

Errors and recovery

Status and code	When	Recovery
`400 VALIDATION_FAILED`	No trigger, an unsupported `mode`, or a body that is not a JSON object	Set a trigger first, and send a supported mode.
`401 AUTHENTICATION_REQUIRED`	No key, or an unknown key	Send a valid key.
`403 API_KEY_PERMISSION_DENIED`	The key has no `workflowBuilder` permission	Grant it.
`404 WORKFLOW_NOT_FOUND`	Unknown id, or another community's workflow	Use an id from this community.
`415 UNSUPPORTED_MEDIA_TYPE`	The body was not declared `application/json`	Send the header.
`429 RATE_LIMITED`	The community's API rate limit was reached	Wait for the window to reset, then retry.
`500 INTERNAL_ERROR`	Unexpected failure	Retry a dry run with bounded backoff.

Retry safety

A dry run is safe to retry: it writes no history, no step status, no member data, and makes no outbound call.

A live test is not safe to retry. It runs every step for real, in order, exactly like a triggered run, so a second accepted call can pay a second reward. After a timeout, read the member's history and the run list before deciding.

Gotchas

The default mode is live. An empty body therefore runs the whole workflow for real: send {"mode":"dry-run"} while you are still editing, and keep the live call for the change you mean to make.

status: "success" means no step failed. It does not mean a simulated step did anything, and it is not a deploy.

A simulated step produces no output, so a later step that reads it is not executed: it is reported as failed with UNRESOLVED_SIMULATED_REFERENCE, and the workflow's status is fail. That is deliberate: an invented value would be worse than an obvious gap. A workflow test's input seeds earlier step results for a single-step test, not for this walk, so it does not lift the block. Test the later step on its own with POST /{workflowId}/nodes/{nodeId}/test and input, or run the workflow live.

The trigger's stored sample result is used when no triggerPayload is sent. Seed every test with the event shape you expect, or you are testing the sample.

A live test leaves no run in the workflow's history, so "test then read the run" is not a sequence. Deploy and fire the trigger for a real run.

A workflow needs nothing validated to be tested: POST /{workflowId}/validate reports the advisory findings, and neither a test nor a deploy refuses on them.

scenario does not exist: one call tests one payload. Send several calls for several events.

Next steps

POST /{workflowId}/validate for the advisory report deploy will repeat in its warnings.

POST /{workflowId}/deploy to make the workflow live.

GET /{workflowId}/runs after a real trigger, to read the run the trace predicted.

Responses

🟢200200 Success

application/json

The per-step trace of the test.

Bodyapplication/json

🟠400400 VALIDATION_FAILED

🟠401401 AUTHENTICATION_REQUIRED / API_KEY_REQUIRED

🟠403403 API_KEY_PERMISSION_DENIED

🟠404404 WORKFLOW_NOT_FOUND

🟠413413 VALIDATION_FAILED

🟠415415 UNSUPPORTED_MEDIA_TYPE

🟠429429 RATE_LIMITED

🔴500500 INTERNAL_ERROR

curl --location 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/test' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mode": "dry-run", "triggerPayload": { "email": "trader@example.com", "trade_id": "T-1024", "volume": "2.5" } }'

{ "data": { "mode": "dry-run", "sideEffects": "none", "workflowId": "65f1a2b3c4d5e6f708192a3b", "status": "success", "trace": [ { "nodeId": "65f1a2b3c4d5e6f708192a3c", "name": "Read member XP", "type": "platform-action", "status": "executed", "output": { "Total XP": 150 }, "warnings": [] }, { "nodeId": "65f1a2b3c4d5e6f708192a3e", "name": "XP over 100?", "type": "router", "status": "executed", "warnings": [] }, { "nodeId": "65f1a2b3c4d5e6f708192a3d", "name": "Add 10 XP", "type": "platform-action", "branch": "XP > 100", "branchIndex": 1, "status": "simulated", "wouldDo": { "action": "post-user-fields" }, "warnings": [] }, { "nodeId": "65f1a2b3c4d5e6f708192a3f", "name": "Notify receiver", "type": "http", "branch": "Otherwise", "branchIndex": 2, "status": "skipped", "warnings": [] } ], "redactedPaths": [] } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request