---
title: "Send the agent a message (submit a run)"
method: POST
path: "/v1/agents/{agentID}/runs"
---

# Send the agent a message (submit a run)

`POST /v1/agents/{agentID}/runs`

## Request

- Base URL: `https://api.plori.ai`
- URL: `https://api.plori.ai/v1/agents/{agentID}/runs`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Submits a run and returns 202 immediately; there is no blocking or SSE mode on this endpoint. Read the reply over the session WebSocket (`GET /v1/ws`), poll `GET /v1/agents/{agentID}/runs/{runID}` for status, or use the MCP `send_workspace_message` tool, which can wait. A run is nondeterministic and billable. Retry only with an `Idempotency-Key`: the same key replays the original run for 24 h (the replay carries `X-Plori-Idempotent-Replay: true`).

## Path parameters

- `agentID` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `message` string: The user message. Exactly one of `message` or `messages` is required; `messages` wins if both are set.
  - `messages` UserInvokeMessage[]
    - `role` 'user', required
    - `content` string, required
    - `parts` UserInvokePart[]
      - `type` 'image' | 'text' | 'pdf', required
      - `path` string
      - `mime` string
      - `name` string
      - `size` integer
      - `sha256` string
      - `w` integer
      - `h` integer
  - `session_id` string: Continue an existing thread; omit to start a new one.
  - `idempotency_key` string
  - `max_turn_tokens` integer: Optional cumulative cache-weighted token ceiling for this run. 0 or omitted: no ceiling for a registered account, whose credit balance is its only spend limit, and 2,000,000 for an anonymous trial. Near the ceiling the agent stops using tools and ends with a reply that says the work so far is saved and that a new message continues the task.
  - `max_advisor_spend_micro_usd` integer, nullable: Advisor completion cap for the turn in micro-USD. Omit the field or send null to use the agent cap. Set 0 to disable advisor completions.
  - `max_turn_seconds` integer: Soft checkpoint for this turn; 0 or omitted = the default.
  - `github_token` string: Job-lifetime contents:read GITHUB_TOKEN for repository checkout. Delivered only to this turn in memory and never persisted; the owning API-key fallback is supported for GHES.
  - `github_server_url` string, uri: HTTPS origin that issued github_token, such as https://github.com or a GHES origin. The token's in-memory Git credential helper is scoped to this host; invalid values fall back to github.com.
  - `callback_url` string
  - `callback_secret` string

## Response `202`

Run submitted. Headers `X-Plori-Run-Id` and `X-Plori-Session-Id` mirror the body.

- object
  - `run_id` string, required
  - `workspace_id` string, uuid: The Workspace the run belongs to; omitted for runs outside a Workspace.
  - `session_id` string, required

## Other responses

- `400`: Malformed request.
- `401`: Missing or invalid credential.
- `402`: Insufficient credits.
- `403`: The resource belongs to another account.
- `404`: Agent or session not found.
- `409`: A request with this Idempotency-Key is still in flight. `Retry-After: 2`.
- `422`: This Idempotency-Key was already used for a different request.
- `429`: Plan concurrency cap or cluster capacity. `Retry-After: 10`.

---

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