> 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` (true, required)
- `model` (string, optional, nullable)
- `chat_id` (string, optional, nullable)
- `save` (boolean, optional, default: false)

## Response

### 200

- Streaming response of `object`.
- `type` (string, required)
- `delta` (string, optional, nullable)
- `tool_call_id` (string, optional, nullable)
- `tool_name` (string, optional, nullable)
- `input` (any, optional)
- `output` (any, optional)
- `result` (object, optional, nullable) — Final result of an agent run: the assistant's answer, the tool calls it made, token usage, and the chat id when the run was persisted.
  - `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)
- `error` (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": "Did annealing temperature affect the hardness of last week's alloy samples?",
  "stream": true,
  "model": "claude-opus-5",
  "save": true
}
```

**Response**

```json
[
  {
    "data": {
      "input": {
        "query": "SELECT anneal_temp_c, AVG(hardness_hv) FROM samples WHERE measured_at >= now() - interval '7 days' GROUP BY anneal_temp_c"
      },
      "tool_call_id": "toolu_01F3gT9vKwXqPz7mAeR2bYcD",
      "tool_name": "sql_query_run",
      "type": "tool_call"
    }
  },
  {
    "data": {
      "output": {
        "results": {
          "columns": [
            "anneal_temp_c",
            "avg"
          ],
          "data": [
            [
              300,
              342
            ],
            [
              200,
              385
            ]
          ]
        },
        "rowCount": 2,
        "success": true
      },
      "tool_call_id": "toolu_01F3gT9vKwXqPz7mAeR2bYcD",
      "tool_name": "sql_query_run",
      "type": "tool_result"
    }
  },
  {
    "data": {
      "delta": "Yes. Across the 24 samples measured last week, samples annealed at 300 °C",
      "type": "text_delta"
    }
  },
  {
    "data": {
      "delta": " averaged 342 HV versus 385 HV for samples annealed at 200 °C — an 11% decrease.",
      "type": "text_delta"
    }
  },
  {
    "data": {
      "result": {
        "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "model": "claude-opus-5",
        "output": "Yes. Across the 24 samples measured last week, samples annealed at 300 °C averaged 342 HV versus 385 HV for samples annealed at 200 °C — an 11% decrease, consistent with the expected softening at higher annealing temperatures. Sample S-0608 (200 °C) was the hardest overall at 401 HV.",
        "tool_calls": [
          {
            "input": {
              "query": "SELECT anneal_temp_c, AVG(hardness_hv) FROM samples WHERE measured_at >= now() - interval '7 days' GROUP BY anneal_temp_c"
            },
            "output": {
              "results": {
                "columns": [
                  "anneal_temp_c",
                  "avg"
                ],
                "data": [
                  [
                    300,
                    342
                  ],
                  [
                    200,
                    385
                  ]
                ]
              },
              "rowCount": 2,
              "success": true
            },
            "tool_call_id": "toolu_01F3gT9vKwXqPz7mAeR2bYcD",
            "tool_name": "sql_query_run"
          }
        ],
        "usage": {
          "input_tokens": 4820,
          "output_tokens": 356,
          "total_tokens": 5176
        }
      },
      "type": "result"
    }
  }
]
```

**SDK Code**

```python
from labric import Labric

client = Labric(
    api_key="YOUR_TOKEN_HERE",
)

client.agent.run_stream(
    prompt="Did annealing temperature affect the hardness of last week\'s alloy samples?",
    model="claude-opus-5",
    save=True,
)

```