---
title: "Start detached agent run"
method: POST
path: "/api/agent/run"
tags: ["Agent"]
---

# Start detached agent run

`POST /api/agent/run`

Starts an agentic conversation loop in detached mode. The agent processes the user's message asynchronously, calling MCP tools as needed. Returns immediately with a `runId` and `sessionId`. Use `/api/agent/runs/{runId}/events` to stream the results via SSE.

## RBAC
Tool execution within the agent loop respects user role permissions. Viewer role can only use read-only tools.

## Iteration Limit
Max 25 iterations per run.

## Query parameters

- `model` 'base' | 'large'

## Headers

- `X-Grafana-Org-Id` string

## Request body

- RunRequest — Request to start an agent run. The backend builds the system prompt and manages context window based on the message type and server-side session history.
  - `message` string, required — User message to send to the agent
  - `type` 'investigation' | 'performance' | 'chat' — Message type that determines which server-side prompt template to use
  - `sessionId` string — Existing session ID to continue (optional, creates new if not provided)
  - `orgName` string — Organization name (optional)
  - `scopeOrgId` string — Scope organization ID (optional)

## Response `200`

Agent run started successfully

- object
  - `runId` string, required — Unique run ID (base64 URL-safe 32-byte token)
  - `sessionId` string, required — Session ID (new or existing)
  - `status` 'running', required — Initial run status
  - `model` 'base' | 'large', required — Effective model selected for this run
  - `modelSource` 'auto' | 'request' | 'session', required — How the effective model was chosen

## Other responses

- `400` — Bad request (invalid parameters or malformed request body)
- `401` — Unauthorized (missing or invalid authentication)
- `500` — Internal server error

---

[API](https://skmtc.net/consensys/apis/ask-o11y-ai-powered-observability-assistant-api.md) · [All operations](https://skmtc.net/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/consensys/ask-o11y-ai-powered-observability-assistant-api/versions/3ccc03eccaef/schema)