---
title: "Start an agent execution"
method: POST
path: "/api/v1/agent-executions"
tags: ["AI"]
---

# Start an agent execution

`POST /api/v1/agent-executions`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/agent-executions`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Runs the tool-using agent (ReAct) loop against a session - the same pipeline the product UI's Agent Mode toggle dispatches to, and the REST equivalent of the `agent_execute` WebSocket command. The run is asynchronous: this returns `202` with an execution id, and the caller polls `GET /api/v1/agent-executions/{id}` until `status` is terminal (`completed`, `failed`, or `aborted`). Nothing is streamed back over REST - for live iteration events, use the WebSocket route instead. Omit `agent_id` to get the profile the session's own surface resolves to, which is what reproduces the in-app toggle. The final reply is also written to the session as a normal chat message, so it appears in history. Naming a tool in `tools` also PRE-APPROVES it for the run: there is no interactive client to answer a permission prompt, so a run that calls an approval-gated tool you did not name fails with that tool named in `error` rather than hanging. Authenticate with an API key (`b4m_live_`) or a JWT.

## Request body

- StartAgentExecutionRequest
  - `session_id` string, required
  - `message` string, required
  - `model` string
  - `agent_id` string
  - `organization_id` string
  - `tools` string[]
  - `max_iterations` integer
  - `temperature` number
  - `max_tokens` integer
  - `thinking` object
    - `enabled` boolean, required
    - `budget_tokens` integer
  - `file_ids` string[]
  - `session_file_ids` string[]
  - `enable_mementos` boolean
  - `enable_lattice` boolean
  - `enable_artifacts` boolean

## Response `202`

Run accepted and dispatched. Poll `tracking_info.poll_url` for status and the answer.

- StartAgentExecutionResponse202
  - `id` string, required
  - `status` 'pending', required
  - `session_id` string, required
  - `model` string, required
  - `timestamp` string, required
  - `tracking_info` object, required
    - `execution_id` string, required
    - `quest_id` string
    - `poll_url` string, required

## Other responses

- `400`: No usable default chat model is configured and none was supplied.
- `401`: Missing or invalid credentials.
- `403`: The API key does not hold any of the required scopes.
- `404`: No session with the given `session_id` is owned by the caller, or `organization_id` names an organization the caller does not belong to. "Exists but is not yours" is reported as 404 too, so neither session ids nor org membership can be probed through this endpoint.
- `405`: The path does not serve this HTTP method.
- `409`: The caller already has the maximum number of agent runs in flight - a per-user cap shared with runs started from the product UI. Wait for one to reach a terminal status before starting another; aborting a run is currently only possible over the WebSocket route.
- `422`: Request failed validation.
- `429`: Per-user rate limit exceeded.
- `502`: The executor could not be dispatched. The run did not start, so a retry is safe.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/db47495b892f?raw)