> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.labric.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.labric.co/_mcp/server.

# Run

POST https://platform.labric.co/api/v1/agent/runs
Content-Type: application/json

Run the Labric data-analysis agent and return its final answer
alongside the tool calls it made. With stream=true the response is
instead a stream of server-sent AgentRunEvent events, closing after a
terminal `result` event that carries the same summary, or an `error`
event if the run fails; prefer streaming for long analyses. Pass chat_id
to continue a saved conversation, or save=true to save the run as a new
chat visible in the web UI; if saving fails, the answer is still returned
but its chat_id is null.

Requires an API key with the `read` scope.

Reference: https://docs.labric.co/api-reference/labric-api/agent/run

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `prompt` (string, required)
- `stream` (false, required)
- `model` (string, optional, nullable)
- `chat_id` (string, optional, nullable)
- `save` (boolean, optional, default: false)

## Response

### 200

- `output` (string, required)
- `model` (string, required)
- `tool_calls` (list of object, required)
  - `tool_call_id` (string, required)
  - `tool_name` (string, required)
  - `input` (any, optional)
  - `output` (any, optional)
- `usage` (object, required)
  - `input_tokens` (integer, optional, nullable)
  - `output_tokens` (integer, optional, nullable)
  - `total_tokens` (integer, optional, nullable)
- `chat_id` (string, optional, nullable)

## Errors

### 400 Bad Request Error

Bad Request

- `detail` (string, required)

### 401 Unauthorized Error

Unauthorized

- `detail` (string, required)

### 403 Forbidden Error

Forbidden

- `detail` (string, required)

### 404 Not Found Error

Not Found

- `detail` (string, required)

### 422 Unprocessable Entity Error

Unprocessable Content

- `detail` (list of map from string to any, required)

### 500 Internal Server Error

Internal Server Error

- `detail` (string, required)

### 502 Bad Gateway Error

Bad Gateway

- `detail` (string, required)

## Examples

**Request**

```json
{
  "prompt": "Which samples from the latest XRD batch show the strongest primary diffraction peak, and how does that compare to the previous batch?"
}
```

**Response**

```json
{
  "output": "In batch XRD-2024-06, sample TF-0612 shows the strongest primary reflection at 2θ = 38.2° with 42,300 counts, followed by TF-0608 at 39,800 counts. The batch median peak intensity is 12% higher than batch XRD-2024-05, consistent with the improved crystallinity expected from the longer annealing step.",
  "model": "claude-opus-5",
  "tool_calls": [
    {
      "tool_call_id": "toolu_01Xk8dQe2RfLmN4vTgH6sJwB",
      "tool_name": "sql_schema_get",
      "input": {},
      "output": {
        "success": true,
        "tableCount": 12
      }
    },
    {
      "tool_call_id": "toolu_01Ym3cVa7PdKqR9nWbE5tLzF",
      "tool_name": "sql_query_run",
      "input": {
        "query": "SELECT sample_name, batch_id, peak_two_theta, peak_intensity FROM xrd_measurements WHERE batch_id IN ('XRD-2024-06', 'XRD-2024-05') ORDER BY peak_intensity DESC"
      },
      "output": {
        "results": {
          "columns": [
            "sample_name",
            "batch_id",
            "peak_two_theta",
            "peak_intensity"
          ],
          "data": [
            [
              "TF-0612",
              "XRD-2024-06",
              38.2,
              42300
            ],
            [
              "TF-0608",
              "XRD-2024-06",
              38.2,
              39800
            ]
          ]
        },
        "rowCount": 48,
        "success": true
      }
    }
  ],
  "usage": {
    "input_tokens": 5210,
    "output_tokens": 412,
    "total_tokens": 5622
  },
  "chat_id": null
}
```

**SDK Code**

```python
from labric import Labric

client = Labric(
    api_key="YOUR_TOKEN_HERE",
)

client.agent.run_stream(
    prompt="Which samples from the latest XRD batch show the strongest primary diffraction peak, and how does that compare to the previous batch?",
)

```