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 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.

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

The Run object

id · string

Unique identifier for the run.

chatId · string

The chat this run belongs to.

status · string

Current status of the run: queued, running, waiting (paused on a waitpoint), completed, failed, or cancelled.

createdAt · string

ISO 8601 timestamp of when the run was created.

updatedAt · string

ISO 8601 timestamp of the last update to the run.

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).
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.

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):

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. 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.

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

Chats

Learn how to create chats and send messages that trigger runs.

Waitpoints

Discover how runs pause and resume for human-in-the-loop interactions.