Camille writes "Is my bike ready?" to her repair shop's WhatsApp number, and the shop's automation starts answering her. That is a run: one contact going through one version of an automation, in her conversation with that number.
A trigger starts a run, or a member does when they hand the conversation back to an automation. If the shop publishes a new version while Camille is still answering, her run stays on the version it started with until it ends.
What does a run's state mean?
Camille's run is waiting while she picks a pickup time, and completed once it reaches its last step.
state.type | Meaning |
|---|---|
running | The run executes a step, such as a wait. |
waiting | A question step, or an ai_agent step, waits for a reply. |
completed | The run reached a step with nothing after it. |
handed_over | A handover step handed the conversation to the members. |
cancelled | Its test ended, or a member wrote in a live chat or started another run. |
failed | The run stopped at a step, for a reason it keeps. |
Why does a run fail?
Say the automation asks the shop's repair software for the bike's status, and the software is down. With no onError path on that http_request step, Camille's run stops failed, and its failure says why.
A run also fails when a message cannot be sent, when WhatsApp or the AI provider stays unavailable, when an ai_agent step neither writes nor takes an exit, or when it reaches a step runs do not execute. The OpenAPI document lists each reason.
How does an agent find out what happened?
Ask your agent why Camille got no answer. It reads the run's state to see where it stopped, then calls listWorkspaceLog with the run's automationRunId to list every decision that led there, as the workspace log explains.
In the API
Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.
- GET
listAutomationRunsList automation runs
/api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs - GET
getAutomationRunGet an automation run
/api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs/{automationRunId}