Sign in

v1

latestOpenAPI 3.0.3MIT2026-07-17323590.7 KB
Agent

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

post/api/agent/run

Query parameters

model'base' | 'large'

Optional explicit LLM app model abstraction to use for this session. Omit to let Ask O11y choose base or large from the task type and message complexity. Once explicitly set on a session, later runs must use the same model.

Headers

X-Grafana-Org-Idstring

Grafana organization ID for multi-tenant isolation. Defaults to '1' if not provided.

Request body

messagestring required

User message to send to the agent

type'investigation' | 'performance' | 'chat'

Message type that determines which server-side prompt template to use

sessionIdstring

Existing session ID to continue (optional, creates new if not provided)

orgNamestring

Organization name (optional)

scopeOrgIdstring

Scope organization ID (optional)

Response

Agent run started successfully

runIdstring required

Unique run ID (base64 URL-safe 32-byte token)

sessionIdstring 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