> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# 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](https://heythere.io/docs/concepts/contacts) going through one [version](https://heythere.io/docs/concepts/versions) of an [automation](https://heythere.io/docs/concepts/automations), in her [conversation](https://heythere.io/docs/concepts/conversations) with that number.

A [trigger](https://heythere.io/docs/concepts/triggers) starts a run, or a member does when they [hand the conversation back](https://heythere.io/docs/concepts/live-chats#how-does-a-member-hand-the-contact-to-an-automation-) 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](https://heythere.io/docs/concepts/steps), 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](https://heythere.io/docs/concepts/tests) ended, or a member wrote in a [live chat](https://heythere.io/docs/concepts/live-chats) 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](https://heythere.io/docs/concepts/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](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `listAutomationRuns`: List automation runs. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs`
- `getAutomationRun`: Get an automation run. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs/{automationRunId}`
