Get a step
GET
/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}
GET /{workflowId}/nodes/{nodeId} needs workflowBuilder.What this endpoint does
GET /runs/{runId} returns.Quick start
Authentication and permission
Authorization: Bearer <API_KEY> with workflowBuilder, for the community that owns the workflow. The step is looked up inside that workflow, so a step id from another workflow or another community answers 404 NODE_NOT_FOUND.| Failure | Meaning | Recovery |
|---|---|---|
403 API_KEY_PERMISSION_DENIED | No workflowBuilder | Grant the permission. |
404 WORKFLOW_NOT_FOUND | The workflow id is unknown in this community | Use an id from the list. |
404 NODE_NOT_FOUND | The step id is not in this workflow | Read the workflow for its step ids. |
Complete examples
{
"data": {
"node": {
"_id": "65f1a2b3c4d5e6f708192a3c",
"name": "Read member XP",
"type": "platform-action",
"order": 1,
"continueOnFailure": false,
"retryOnFailure": false,
"options": {
"action": "get-user-fields",
"selectUser": { "type": "email", "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"] },
"fields": [{ "label": "Total XP", "field": "total_xp" }]
},
"status": "success"
},
"revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
"redactedPaths": []
}
}Success and readback
200 with { node, revision, redactedPaths } and the revision in the ETag header. The revision is the workflow's, not the step's: it is the value to send as If-Match on the next write.order is its position in the authored order, and its branch membership is visible on the router, not here.Errors and recovery
| Status and code | When | Recovery |
|---|---|---|
400 VALIDATION_FAILED | An id is not 24 hexadecimal characters | Use the ids exactly as returned. |
401 AUTHENTICATION_REQUIRED | No key, or an unknown key | Send a valid key. |
403 API_KEY_PERMISSION_DENIED | No workflowBuilder | Grant the permission. |
404 WORKFLOW_NOT_FOUND | Unknown workflow id, or another community's workflow | Use an id from this community. |
404 NODE_NOT_FOUND | The step is not part of this workflow | Read the workflow for its step ids. |
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 with bounded backoff. |
Retry safety
status can change between reads because of a run, but revision changes only when authored configuration changes.Gotchas
status on a step is run state from the last execution, not part of the configuration, and it is not covered by the revision.["__REDACTED__"] and listed in redactedPaths.branchName, branchType, conditions and workflowNodeIds.Next steps
PATCH /{workflowId}/nodes/{nodeId} to change this step.POST /{workflowId}/nodes/{nodeId}/test with mode: "dry-run" to check it without side effects.GET /{workflowId} when you need the whole workflow.Request
Path Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3c' \
--header 'Authorization: Bearer <API_KEY>'Response Response Example
200 - 200 Success
{
"data": {
"node": {
"_id": "65f1a2b3c4d5e6f708192a3c",
"name": "Read member XP",
"type": "platform-action",
"order": 1,
"continueOnFailure": false,
"retryOnFailure": false,
"options": {
"action": "get-user-fields",
"selectUser": {
"type": "email",
"value": [
"{{65f1a2b3c4d5e6f708192a41.email}}"
]
},
"fields": [
{
"label": "Total XP",
"field": "total_xp"
}
]
}
},
"revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
"redactedPaths": []
}
}Modified at 2026-10-28 04:47:19