Returning.AIDocs
v1

API reference / Workflow Builder

.md

Get one run

Returns one run with its per-step results, so a caller can see what each step produced and where a run failed.

Last updated 28 Oct 2026API v1

Method
GET
Path
https://api.returning.ai/v1/workflow-builder/data-workflows/runs/{runId}
Permission
workflowBuilder
Retries
Safe to retry: it writes nothing.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
workflowBuilder

The run is read only if it belongs to the key's community, so a run id from another community answers 404 RUN_NOT_FOUND.

FailureMeaningRecovery
403 API_KEY_PERMISSION_DENIEDNo workflowBuilderGrant the permission.
404 RUN_NOT_FOUNDUnknown run id, or a run of another communityUse a run id from GET /{workflowId}/runs.

Behaviour#

Credentials in the results are replaced by the redaction marker and listed in redactedPaths.

The run id is enough on its own; the route is not nested under the workflow. The lookup is still scoped to the key's community.

Request#

Path parameters#

runId#stringREQUIRED
Run identifier: 24 hexadecimal characters.

Rule^[0-9a-fA-F]{24}$

Eg65f1a2b3c4d5e6f708192a40

Headers#

Authorization#stringREQUIRED
Community API key: Bearer <API_KEY>.

EgBearer <API_KEY>

Watch for

  • results is null or partial for a run that did not reach every step, so treat a missing key as "did not run", not as an empty result.
  • Credentials inside a recorded result are replaced by ["__REDACTED__"] and named in redactedPaths. A secret an author typed into a raw body template is returned as recorded.
  • A result that came from a leaderboard outside the key's community is replaced by a redacted placeholder with the code LEADERBOARD_NOT_FOUND, rather than returned.
  • The route works for a run of a workflow that has since been undeployed. A deleted workflow takes its runs with it.
More examples and details
JSON
{
  "data": {
    "_id": "65f1a2b3c4d5e6f708192a40",
    "workflowId": "65f1a2b3c4d5e6f708192a3b",
    "communityId": "65f1a2b3c4d5e6f708192a50",
    "status": "success",
    "startTime": "2026-10-24T10:02:14.000Z",
    "endTime": "2026-10-24T10:02:19.000Z",
    "createdAt": "2026-10-24T10:02:13.000Z",
    "updatedAt": "2026-10-24T10:02:19.000Z",
    "results": {
      "65f1a2b3c4d5e6f708192a3c": { "status": "success", "result": { "XP": 150 } },
      "65f1a2b3c4d5e6f708192a3e": { "status": "success", "result": { "branches": [{ "branchName": "XP > 100", "branchIndex": 1, "evaluation": true }, { "branchName": "Otherwise", "branchIndex": 2, "evaluation": false }] } },
      "65f1a2b3c4d5e6f708192a3d": { "status": "success", "result": { "XP": 160 } },
      "65f1a2b3c4d5e6f708192a3f": { "status": "skipped" }
    },
    "redactedPaths": []
  }
}

curl --request GET \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/runs/<runId>' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

HTTP 200 with the run in data. results is an object keyed by step id, so a caller can join it to the workflow's steps:

  • results[stepId].status is that step's outcome: success, fail or skipped.
  • A router's result lists every branch as {branchName, branchIndex, evaluation}, with 1-based branchIndex; the write side counts branches from 0.
  • results[stepId].result is what the step produced.
  • A step that did not run in this execution is absent or skipped, depending on how the run reached it.

This is the readback for a real run: after firing a trigger, poll GET /{workflowId}/runs for the new run id and read it here. For a reward step, what settles it is this result plus the member's own field value, read through the platform API.

data#object
One run with its per-step results.

Eg{ ... }

_id#string
Run identifier.

Eg"65f1a2b3c4d5e6f708192a40"

workflowId#string
Workflow that ran.

Eg"65f1a2b3c4d5e6f708192a3b"

communityId#string
Community of the workflow.

Eg"65f1a2b3c4d5e6f708192a50"

status#string
success, error, running, queued or unknown.

Eg"success"

startTime#string
Start time, when recorded.

Eg"2026-10-24T10:02:14.000Z"

endTime#string
Finish time, when recorded.

Eg"2026-10-24T10:02:19.000Z"

createdAt#string
Record creation time.

Eg"2026-10-24T10:02:13.000Z"

updatedAt#string
Last change to the record.

Eg"2026-10-24T10:02:19.000Z"

results#object
Step results keyed by step id, with credentials replaced.

RuleNullable

Eg{ ... }

redactedPaths#string[]
Credential locations replaced in this response.

Eg[]

{
  "data": {
    "_id": "65f1a2b3c4d5e6f708192a40",
    "workflowId": "65f1a2b3c4d5e6f708192a3b",
    "communityId": "65f1a2b3c4d5e6f708192a50",
    "status": "success",
    "startTime": "2026-10-24T10:02:14.000Z",
    "endTime": "2026-10-24T10:02:19.000Z",
    "createdAt": "2026-10-24T10:02:13.000Z",
    "updatedAt": "2026-10-24T10:02:19.000Z",
    "results": {
      "65f1a2b3c4d5e6f708192a3c": {
        "status": "success",
        "result": {
          "Total XP": 150
        }
      },
      "65f1a2b3c4d5e6f708192a3e": {
        "status": "success",
        "result": {
          "branches": [
            {
              "branchName": "XP > 100",
              "branchIndex": 1,
              "evaluation": true
            },
            {
              "branchName": "Otherwise",
              "branchIndex": 2,
              "evaluation": false
            }
          ]
        }
      },
      "65f1a2b3c4d5e6f708192a3d": {
        "status": "success",
        "result": {
          "XP": 160
        }
      }
    },
    "redactedPaths": []
  }
}

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request
The run id is not 24 hexadecimal characters. Use the id exactly as returned.
401AUTHENTICATION_REQUIREDFix the request
No key, or an unknown key. Send a valid key.
401API_KEY_REQUIREDFix the request
A valid admin session was used, because this API accepts community API keys only. Use a community API key.
403API_KEY_PERMISSION_DENIEDFix the request
No workflowBuilder. Grant the permission.

Fix the data01

404RUN_NOT_FOUNDFix the data
Unknown run id, or a run of another community. Use a run id from the list.

Retry with backoff02

429RATE_LIMITEDRetry with backoff
The community's API rate limit was reached. Wait for the window to reset, then retry.
500INTERNAL_ERRORRetry with backoff
Unexpected failure. Retry with bounded backoff.

Retries

Safe to retry: it writes nothing. A run that is still running can gain results between two reads, so poll while the status is transient and stop when it is success or error.

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED",
    "errors": [
      {
        "path": "params.workflowId",
        "message": "Id must be a 24 character hex string"
      }
    ],
    "requestId": "3f4d0e8b-7a6c-4f1e-9b2d-5a7c8e1f0a3b"
  },
  "message": "API request rejected error.",
  "detail": "The request body is not valid.",
  "solution": "Read error detail and try again."
}

Next step#

Retry a failed runPOST/v1/workflow-builder/data-workflows/runs/{runId}/retry