---
title: "Run a deployed Agent"
method: POST
path: "/v1/agents/run"
tags: ["Agent Operations"]
---

# Run a deployed Agent

`POST /v1/agents/run`

Execute an agent by sending the provided message to the agent service. Returns a detailed response containing the conversation messages, logs, and metadata.

## Request body

- RunRequest
  - `agent_id` string, required — Unique identifier for the agent.
  - `message` union, required — The message or command to be sent to the agent.
    - string
    - object
  - `agent_history` unknown[], nullable — List of prior messages; defaults to empty list.
    - unknown
  - `thread_id` string, nullable — Unique identifier for the chat session.
  - `hitl_decision` 'approve' | 'edit' | 'reject', nullable — Human-in-the-loop decision for the agent.

## Response `200`

Successful Response

- AgentResponse
  - `request_metadata` ResponseMeta
    - `request_id` string, nullable — Unique request identifier for tracing and support.
  - `response` object[], required
  - `usage` UsageStats, required
    - `credits_charged` CreditUsage[]
      - `agent_name` string, required
      - `number_of_runs` integer, required
      - `credit_consumed` integer, required
    - `total_credits_charged` integer
  - `additional_metadata` AdditionalMetadata, required
    - `thread_id` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-03-15** `3517ca6a2c04` — 1 breaking, 1 info
  - removed `subschema #1` from the `message` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `message` request property `anyOf` list
- **2026-03-15** `536abd065ab0` — 13 breaking, 8 info
  - the `message` request property type changed from `string` to no type
  - the response property `additional_metadata/thread_id` became optional for the status `200`
  - the response property `response/items/additionalProperties/llmresponse` became optional for the status `200`
  - the response property `response/items/additionalProperties/reasoning` became optional for the status `200`
  - …17 more
- **2026-02-11** `c9a09aaa6236` — 1 breaking, 5 info
  - the response's body type changed from no type to `object` for status `200`
  - added the new optional request property `thread_id`
  - added the optional property `request_metadata` to the response with the `200` status
  - added the required property `additional_metadata` to the response with the `200` status
  - …2 more
- **2025-06-09** `10ce21f8546b` — 2 breaking, 4 info
  - the response's body type changed from `object` to no type for status `200`
  - removed the required property `reply` from the response with the `200` status
  - added the new optional request property `agent_history`
  - removed the non-success response with the status `400`
  - …2 more
- …earlier changes not shown

[Full history](https://skmtc.dev/svahnar/apis/svahnar-apis/changes/v1/agents/run/post.md)

---

[API](https://skmtc.dev/svahnar/apis/svahnar-apis.md) · [All operations](https://skmtc.dev/svahnar/apis/svahnar-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/svahnar/svahnar-apis/revisions/02cca47c900a/schema)