> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs

> List, get, cancel and retry the runs of a workflow.

<Note>
  These endpoints are for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

A run is one trip of one contact or event through a workflow.

## List runs

* `GET /v1/workflows/{id}/runs`: runs of one workflow.
* `GET /v1/workflows/runs`: runs of every workflow in a workspace. An account key must send `workspaceId`. Add `workflowId` to see one workflow.

Both list newest first and take these query parameters:

<ParamField query="status" type="string" optional>
  One of `running`, `waiting`, `completed`, `failed` or `cancelled`. `running` includes runs that have not started.
</ParamField>

<ParamField query="limit" type="integer" optional default="50">
  How many to return, 1 to 100.
</ParamField>

<ParamField query="offset" type="integer" optional default="0">
  How many to skip.
</ParamField>

```json Response theme={null}
{
  "items": [
    {
      "id": "623e4567-e89b-12d3-a456-426614174000",
      "workflowId": "123e4567-e89b-12d3-a456-426614174000",
      "workspaceId": "223e4567-e89b-12d3-a456-426614174000",
      "status": "failed",
      "triggerType": "contact_created",
      "isTest": false,
      "errorMessage": "This step could not finish.",
      "startedAt": "2026-10-11T09:00:00Z",
      "completedAt": "2026-10-11T09:00:04Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}
```

A run's `status` is `pending`, `running`, `waiting`, `completed`, `failed` or `cancelled`.

A run's `triggerType` is what started it: `contact_created`, `contact_tagged`, `contact_tag_added`, `contact_tag_removed`, `call_completed`, `conversation_completed`, `conversation_started`, `contact_replied`, `webhook`, `schedule`, `pipedrive_person_updated`, or `manual` for a contact you enrolled.

## Get a run

`GET /v1/workflows/{id}/runs/{runId}`

One run with the result of each step it reached.

```json Response theme={null}
{
  "id": "623e4567-e89b-12d3-a456-426614174000",
  "workflowId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "223e4567-e89b-12d3-a456-426614174000",
  "workflowName": "Welcome text",
  "status": "completed",
  "triggerType": "contact_created",
  "isTest": false,
  "errorMessage": null,
  "contactId": "523e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-10-11T09:00:00Z",
  "startedAt": "2026-10-11T09:00:00Z",
  "completedAt": "2026-10-11T09:00:02Z",
  "steps": [
    {
      "stepId": "text",
      "name": "text",
      "type": "sendSms",
      "status": "completed",
      "startedAt": "2026-10-11T09:00:01Z",
      "completedAt": "2026-10-11T09:00:02Z",
      "errorMessage": null
    }
  ]
}
```

A step's `name` is the name it has in the dashboard editor. A step with no name there shows its id.

`errorMessage` is a plain line. Some errors have their own line, like "The contact has DND on." or "The contact has no phone number." Every other error reads "This step could not finish." We never send the raw error text. The step that failed has the same line as the run.

## Cancel a run

`POST /v1/workflows/{id}/runs/{runId}/cancel`

Stop a run that has not finished. It answers with the run's `id`, `workflowId`, `status` and `completedAt`. A run that has finished gets `409`.

## Retry a run

`POST /v1/workflows/{id}/runs/{runId}/retry`

Resume a failed run from the step that failed last. Steps that finished before it do not run again, and the run keeps its `id`. It answers `200` with the run's `id`, `workflowId` and `status`, which is `running`.

The failed step runs again. So a step that may already have sent its message or call can't be retried. That is a step that timed out, failed after it started sending, or placed a call that got no answer back.

A webhook your endpoint refused can be retried. That is a `4xx` error other than `408` or `429`, or a redirect we could not follow. It will be sent again. A webhook that got a `5xx`, `408` or `429` answer, or no answer in time, can't be retried.

These runs get `409`:

* A run that is not failed: cancelled, still going, already being retried, or completed.
* A run with no failed step to resume from.
* A run where steps ran after its failed step.
* A run our system stopped because it stalled.
* A run whose failed step may already have sent its message or call.
* A run whose contact has restricted processing.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.nedzo.ai/v1/workflows/123e4567-e89b-12d3-a456-426614174000/runs/623e4567-e89b-12d3-a456-426614174000/retry" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

## Errors

| Status | When |
| - | - |
| `400` | A query parameter is wrong, an account key sent no `workspaceId` to the workspace list, or a retry would run a step that turns DND off. |
| `402` | The account has no plan, or its subscription is not active. |
| `403` | Your plan is not VIP. A retry needs workflows on your plan and a workspace that is not locked. |
| `404` | No workflow or run has this id, or it is not in this key's scope. |
| `409` | The run can't be cancelled or retried in its current state, its failed step may already have sent its message or call, or its contact has restricted processing. |
| `502` | A retry could not check the workspace or plan status. Try again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.