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

# Messages and runs

> Talk to an agent, then read what it actually did.

A run is one execution of an agent. These three tools are how you test an agent without first inventing a routine for it, and how you find out why the answer was not what you expected.

## send\_message

Talks to an agent and waits for its answer.

<ParamField body="agentId" type="string" required />

<ParamField body="message" type="string" required />

<ParamField body="sessionId" type="string">
  Continue an earlier conversation. Omit to start a new one.
</ParamField>

<ParamField body="waitSeconds" type="number">
  How long to wait for the answer. Default `120`, maximum `600`.
</ParamField>

If the agent is still working when the wait runs out, the call returns `status: "running"` with a `runId`, a `note`, and the run carries on in the background. Poll `get_run` for the result.

```json Response theme={"system"}
{
  "runId": "…",
  "status": "done",
  "sessionId": "…",
  "provider": "anthropic",
  "model": "claude-sonnet-5",
  "trigger": "api",
  "steps": 7,
  "inputTokens": 18422,
  "outputTokens": 913,
  "totalTokens": 19335,
  "costUsd": 0.0741,
  "startedAt": "2026-08-15T09:12:04.000Z",
  "finishedAt": "2026-08-15T09:12:41.000Z",
  "error": null,
  "output": "Done. I added 14 rows to the leads table and flagged 3 duplicates."
}
```

<Note>
  An agent can pause mid-run to ask you something or request an approval. When that happens the run finishes with the question waiting in the app, and `output` carries the agent last message. See [Human in the loop](/agents/human-in-the-loop).
</Note>

## list\_runs

Recent executions of an agent, newest first.

<ParamField body="agentId" type="string" required />

<ParamField body="limit" type="number">
  Default `20`, maximum `200`.
</ParamField>

Each run carries the same fields as the response above, without `output`. Use it to see whether a scheduled task or a webhook actually did anything.

The `trigger` field tells you where the run came from: `chat`, `api`, `schedule:<slug>` or `trigger:<slug>`.

## get\_run

One execution in full.

<ParamField body="agentId" type="string" required />

<ParamField body="runId" type="string" required />

<ParamField body="includeToolCalls" type="boolean">
  Also return every tool the agent called, with its input and its result.
</ParamField>

```json Response with includeToolCalls theme={"system"}
{
  "runId": "…",
  "status": "error",
  "error": "Connector notion is not connected",
  "output": null,
  "toolCalls": [
    {
      "step": 1,
      "tool": "memory_recall",
      "input": "{\"query\":\"weekly report format\"}",
      "result": "{\"memories\":[…]}",
      "isError": false,
      "durationMs": 82
    }
  ]
}
```

Run statuses are `running`, `done`, `error` and `cancelled`. `costUsd` is the model cost of that run, and is `null` while it is still running.