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

# Test and monitor Agentic Workflows

> Test a workflow version, read each run step by step in the Runs tab, cancel or resume runs, and fix common failures before and after you activate.

Test a saved workflow version on data you choose, then follow every run in the **Runs** tab: which path it took, what each step received and returned, and why a step failed. Do both before you activate a workflow and whenever it doesn't do what you expect.

> [!NOTE]
>
> Open a workflow in [Agentic Workflows](https://platform.open.cx/workflows). **Test** needs **Workflows** (Write) or **Run workflows** (Write). The **Runs** tab needs **Workflows** (Read); canceling and resuming runs needs **Workflows** (Write).

## Run a test

**1. Select a saved version**

Pick a version in the version menu next to the workflow name. **Test** is turned off while the editor shows your draft (**This workflow is a draft and cannot be tested**), so click **Save** first. The version doesn't need to be active.

**2. Open Test Workflow**

Click **Test**. The **Test Workflow** dialog asks for the data the trigger would normally provide. The fields depend on the trigger:

| Field | What to enter |
| - | - |
| **Session** | A session number. The matching session appears below so you can check it's the right one. |
| **Contact** | Search by name, email or phone. |
| Assignee | **Unassigned**, **AI Agent** or a teammate. |
| Text, number, date, choice, true/false and JSON fields | The value to test with. JSON must be valid. |

**3. Start the run**

Click **Test**. The editor switches to the **Runs** tab and follows the run step by step as it happens.

> [!WARNING]
>
> A test run executes every step with all its side effects. Replies, emails and WhatsApp templates reach the customer, sessions are tagged, assigned or closed, and HTTP and Slack steps call the real endpoints. Test on a session you own, such as one you opened yourself in the widget.

## What's different about a test run

| Test runs… | Details |
| - | - |
| Run the version you selected | Even if it's not active, and even if another version is active. |
| Are labeled **Test** | In the runs list and on the run itself. |
| Don't add a timeline entry | Real runs on a session add **Workflow triggered** to the session timeline in the inbox; test runs don't. Messages and notes the steps write still appear. |
| Aren't stopped by a billing limit | A workflows limit in [Settings → Billing](https://platform.open.cx/settings/billing) never blocks a test. |
| Still send run webhooks | `workflow.run.succeeded` and `workflow.run.failed` are sent with `is_test_run: true`. |

Classical IVR steps such as **Speak Text** and **Transfer Call** need a live call, so they fail in a test run. Test those with a real call to the IVR number.

## Read the Runs tab

The **Runs** tab appears after the first save. It lists the runs of the version on the canvas, newest first. Switch versions to see their runs.

Each row shows when the run started, **Test** for test runs, a short run ID, how it started (**Automatic**, **Manual** or **Scheduled**) and how long it took. Use **Search runs...** and the filter button to narrow by **STATUS** or **DATE RANGE** (**Today**, **3d**, **7d**, **30d**). Click the refresh icon to load new runs.

Open a run to paint it on the canvas: each step gets a status badge, and steps the run never reached stay plain. The run panel shows:

* The status, how the run started, its duration and the run ID (click to copy). Use the arrows to move to a newer or older run.
* **Failed at**, naming the step that failed and its error. Click it to open the step.
* **Steps**: every step in the order it ran. Use ↑ and ↓ to move between steps; the canvas follows.
* **Output**: what the run returned, when it ends with a step such as **Aggregate Workflow Results**.
* **Logs**: the run's log, in order.

Click a step to see its **Input** and **Output**. The trigger shows its **Payload**, an If Block shows which branch it took, and a failed step shows **This step failed** with the error. Right-click a step for **Copy input**, **Copy output**, **Copy step ID** and **Edit this step**, which takes you back to the editor with that step open.

## Run statuses

| Status | Shown in filters as | Meaning |
| - | - | - |
| **Queued** | **Idle** | The run is waiting to start. |
| **Running** | **In Progress** | Steps are executing. |
| **Waiting** | **Waiting** | A **Wait** step paused the run. The step shows when it picks up again. |
| **Completed** | **Completed** | Every step on the path finished. |
| **Failed** | **Failed** | A step or condition failed. The run stopped there. |
| **Canceled** | **Canceled** | Someone canceled the run. |

Steps can also show **Skipped**.

## Cancel or resume a run

* **Cancel run** stops a run that is running or waiting. Steps that already ran are not undone.
* **Resume** restarts a failed or queued run with the data it originally received. It starts again from the first step, so steps that completed before the failure run a second time. Check what they did (a reply already sent, for example) before you resume.

## Common failure states

| What you see | What it means |
| - | - |
| `No session found with this ticket number for this organization` or `Invalid ticket number` | A step's **Ticket Number** is empty or doesn't match a session. Open the step's **Input** and check the variable it uses. |
| `This workflow is paused until <date> because its billing limit is reached.` | The workflows limit in Settings → Billing is reached. New runs don't start until the 1st of next month (UTC), or until you change the limit with **Edit limit**. |
| `This action has reached its limit of <n> call(s) for this conversation and cannot be performed again.` | An **AI Trigger** workflow hit its **Max Calls Per Session** in this session. |
| `Speech requires a live call`, `Team transfer requires a live call`, `Voicemail requires a live IVR call` | A Classical IVR step ran outside a live IVR call, for example in a test run. |
| **The run failed** with no step named | The run failed before any step did, for example while checking an If Block condition. The reason is in the card and in **Logs**. |
| A step with a warning badge in the editor | A required input is missing. Fix it before you save or activate. |

## Get notified about runs

To send run results to your own systems, subscribe to `workflow.run.succeeded` and `workflow.run.failed` in [Settings → Webhooks](https://platform.open.cx/settings/webhooks). Failure events include the workflow name, the session the run acted on (empty for cron, webhook, form and manual triggers) and the error. See [Webhooks setup](https://docs.open.cx/resources/webhooks-setup.md).

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| **Test** is greyed out | The editor shows your draft. | Click **Save**, then test the new version. |
| The workflow never runs on real events | No version is active, or the trigger's **Channels**, **Directions** or **Statuses** filters exclude the session. | Activate a version and check the trigger's filters. |
| The AI never calls an **AI Trigger** workflow | It isn't active, the session's channel isn't in its **Channels**, or **The Goal of the Workflow** doesn't match what customers ask. | Activate it, add the channel, and describe the goal the way customers phrase the request. |
| None of the above | | Contact OpenCX support with the run ID from the run panel. |

***

## Related Documentation

> [card] [Build a workflow](https://docs.open.cx/workflows/build-a-workflow.md)
>
> Re-check steps, variables, versions.

> [card] [Triggers and steps](https://docs.open.cx/workflows/triggers-and-steps.md)
>
> Trigger data and step requirements.

> [card] [Workflows overview](https://docs.open.cx/workflows/introduction.md)
>
> Life cycle and permissions.

> [card] [Webhooks setup](https://docs.open.cx/resources/webhooks-setup.md)
>
> Receive run events.


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