Automations

Runs: follow each customer through an automation

Follow one customer through an automation, see where they stand, and find out why it stopped when it failed.

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.typeMeaning
runningThe run executes a step, such as a wait.
waitingA question step, or an ai_agent step, waits for a reply.
completedThe run reached a step with nothing after it.
handed_overA handover step handed the conversation to the members.
cancelledIts test ended, or a member wrote in a live chat or started another run.
failedThe 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

    listAutomationRuns

    List automation runs

    /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs
  • GET

    getAutomationRun

    Get an automation run

    /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs/{automationRunId}