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

# Agent Runs: How the AI Processes Your Messages

> A Run is created each time you send a message. It tracks the agent execution lifecycle, tool calls, streaming output, and completion status.

A Run represents one full agent turn from the moment you send a message to when the agent finishes processing. Every time you [post a message](/concepts/chats) to a chat, the API creates a Run behind the scenes. It tracks the agent's execution lifecycle, including status changes, tool calls, streaming output, and final completion.

<Note>
  This page uses the public, API-key-authenticated surface at `https://api.vyomflow.co.in/api/public/v1` — see [Authentication](/authentication). The internal `/api/v1` surface (session-token only) backs the first-party web app and is not documented here.
</Note>

## The Run object

<ResponseField name="id" type="string">
  Unique identifier for the run.
</ResponseField>

<ResponseField name="chatId" type="string">
  The chat this run belongs to.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the run: `queued`, `running`, `waiting` (paused on a waitpoint), `completed`, `failed`, or `cancelled`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the run was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the last update to the run.
</ResponseField>

## Lifecycle

When you send a message, the Run moves through the following states:

1. **queued** — the run has been created and dispatched but hasn't started executing yet.
2. **running** — the agent is actively executing, making tool calls and generating output.
3. **waiting** — the run is paused on an open waitpoint (see [Waitpoints](/concepts/waitpoints)).
4. **completed**, **failed**, or **cancelled** — the run has finished.

Only one run can be active per chat at a time. Sending a new message while a run is still active on that chat returns `409 CONFLICT`, not a queued second run.

## Cancelling a run

You can stop an active run at any time (requires the `runs:write` scope). Any credits reserved but not yet consumed are released back to your balance. Cancellation is idempotent — calling it again on an already-terminal run just returns the run's current state.

```bash theme={null}
curl -X POST https://api.vyomflow.co.in/api/public/v1/runs/{runId}/cancel \
  -H "Authorization: Bearer $VYOMFLOW_API_KEY"
```

## Streaming

To follow a run's progress in real time, open the SSE stream (requires the `runs:read` scope):

```bash theme={null}
curl -N --http1.1 \
  -H "Authorization: Bearer $VYOMFLOW_API_KEY" \
  https://api.vyomflow.co.in/api/public/v1/runs/{runId}/stream
```

The full event-type reference, resume semantics, and reconnect protocol are covered in [Streaming](/streaming). If your connection drops and you don't want to reconnect the stream, `GET /api/public/v1/runs/{runId}` (`runs:read`) is the REST recovery path — it returns the same run object described above.

## Error states

If a run fails due to insufficient credits, it ends with a `402` admission error before any provider call is made. This protects your balance from partial execution charges. For more details on how credits are reserved and refunded, see [Credits](/credits).

Runs can also fail due to provider errors or invalid tool responses. In all failure cases, the run status becomes `failed` and the error details are available through the event stream or by fetching the run directly.

## Related concepts

<CardGroup cols={2}>
  <Card title="Chats" href="/concepts/chats">
    Learn how to create chats and send messages that trigger runs.
  </Card>

  <Card title="Waitpoints" href="/concepts/waitpoints">
    Discover how runs pause and resume for human-in-the-loop interactions.
  </Card>
</CardGroup>