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

# Start detached agent run

`POST /api/agent/run`

## Request

- Base URL: `/api/plugins/consensys-asko11y-app/resources` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/plugins/consensys-asko11y-app/resources/api/agent/run`
- Auth: one of:
  - API key in cookie `grafana_session`
  - HTTP bearer

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 50 iterations per run. Alert investigations (`type=investigation`) allow 60.

## Query parameters

- `model` 'base' | 'large'

## Headers

- `X-Grafana-Org-Id` string

## Request body

- RunRequest: Request to start an agent run. The backend resolves skills (explicit selection, legacy type mapping, or message triggers), builds the system prompt, and manages the context window based on 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
  - `skills` string[]: Skill names to explicitly activate for this run (optional). Unknown, disabled, or hidden names return 400.
  - `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

## Changes

- **2026-09-07** `68d0f5cf753e`: 1 info
  - added the new optional request property `skills`
- **2026-05-29** `642c928dd8e4`: 2 info
  - added the required property `model` to the response with the `200` status
  - added the required property `modelSource` to the response with the `200` status
- **2026-05-21** `c2ffd094cb5d`: 1 info
  - added the new optional `query` request parameter `model`
- **2026-02-18** `5e7e9a233e2d`: 2 breaking, 1 warning
  - removed the required property `model` from the response with the `200` status
  - removed the required property `modelSource` from the response with the `200` status
  - deleted the `query` request parameter `model`

[Operation history](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/changes/api/agent/run/post.md)

---

[API](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api.md) - [All operations](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/consensys/apis/ask-o11y-ai-powered-observability-assistant-api/revisions/ee3ccd0f186d?raw)