List the runs of a workflow
GET
/v1/workflow-builder/data-workflows/{workflowId}/runs
GET /{workflowId}/runs needs workflowBuilder.What this endpoint does
GET /runs/{runId} for the per-step results.Quick start
Authentication and permission
Authorization: Bearer <API_KEY> with workflowBuilder, on a workflow of the key's community. Runs are scoped to the workflow and to the community, so this route cannot be used to read another community's runs.| Failure | Meaning | Recovery |
|---|---|---|
403 API_KEY_PERMISSION_DENIED | No workflowBuilder | Grant the permission. |
404 WORKFLOW_NOT_FOUND | Unknown id, or another community's workflow | Use an id from this community. |
Complete examples
{
"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"
},
{
"_id": "65f1a2b3c4d5e6f708192a45",
"workflowId": "65f1a2b3c4d5e6f708192a3b",
"communityId": "65f1a2b3c4d5e6f708192a50",
"status": "error",
"startTime": "2026-10-24T09:44:02.000Z",
"endTime": "2026-10-24T09:44:05.000Z",
"createdAt": "2026-10-24T09:44:01.000Z",
"updatedAt": "2026-10-24T09:44:05.000Z"
}
],
"meta": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
}200, not an error:{
"data": [],
"meta": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 }
}Success and readback
200 with data (an array of run summaries) and meta (page, limit, total, totalPages).status is one of success, error, running, queued or unknown. startTime and endTime are present when the run reached those points. The list is the readback that proves a deploy, a live test or a retried run actually executed.totalPages is 0 when there are no runs.Errors and recovery
| Status and code | When | Recovery |
|---|---|---|
400 VALIDATION_FAILED | limit above 100, a non-numeric page, or an unknown status | Fix the query value. |
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 id, or another community's workflow | Use an id from this community. |
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
running to success in place. Treat a page as a snapshot and poll for a specific run id rather than comparing whole pages.Gotchas
status is the workflow's outcome, not the outcome of every step. A workflow can be success while a step was skipped, and an error run can still have applied some steps. Read the run detail for the step results.running and queued are transient. Poll with a bounded interval instead of a fixed sleep.GET /runs/{runId}, redacted.404.Next steps
GET /runs/{runId} for the per-step results of one run.POST /runs/{runId}/retry for a failed run.GET /{workflowId} to check the configuration the run used.Request
Path Params
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/runs?page=1&limit=20&status=success' \
--header 'Authorization: Bearer <API_KEY>'Response Response Example
200 - 200 Success
{
"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"
},
{
"_id": "65f1a2b3c4d5e6f708192a45",
"workflowId": "65f1a2b3c4d5e6f708192a3b",
"communityId": "65f1a2b3c4d5e6f708192a50",
"status": "error",
"startTime": "2026-10-24T09:44:02.000Z",
"endTime": "2026-10-24T09:44:05.000Z",
"createdAt": "2026-10-24T09:44:01.000Z",
"updatedAt": "2026-10-24T09:44:05.000Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 2,
"totalPages": 1
}
}Modified at 2026-10-28 04:53:02