---
title: "Run an agent"
method: POST
path: "/v1/agents/{agent_id}/runs"
tags: ["Agents"]
---

# Run an agent

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

Start a new run for an agent.

Runs always execute the agent's live published version, so the agent must be
published first with `POST /v1/agents/{agent_id}/publish`. Unpublished drafts
cannot be run.

## Path parameters

- `agent_id` string, uuid, required — The ID of the agent to run.

## Request body

- RunAgentRequest — Request body for starting an agent run.
  - `inputs` object — Input values for the run. Keys should match the property names defined in `schema.input`. Omit the request body when the agent does not require inputs.

## Response `202`

Successful Response

- AcceptedAgentRun — Run details returned after a run request is accepted.
  - `id` string, uuid, required — Unique ID for the accepted run.
  - `agent_id` string, uuid, required — Unique ID of the agent for this run.
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'skipped' | 'unknown', required — Current execution status for an agent run.
  - `started_at` string, date-time, nullable — When the run started, if execution began immediately.

## Other responses

- `422` — Validation Error

## Changes

- **2026-06-17** `56d428ca479f` — 1 breaking, 1 warning, 2 info
  - the request's body type/format changed from `object`/`` to ``/``
  - removed the request property `inputs`
  - added `#/components/schemas/RunAgentRequest, subschema #2` to the request body `anyOf` list
  - request body became optional
- **2026-05-01** `c55c2a1636c3` — 1 info
  - the endpoint scheme security `BearerAuth` was added to the API

[Change history](https://skmtc.dev/cooper-square-technologies/apis/external-api/changes/v1/agents/:agent_id/runs/post.md)

---

[API](https://skmtc.dev/cooper-square-technologies/apis/external-api.md) · [All operations](https://skmtc.dev/cooper-square-technologies/apis/external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cooper-square-technologies/external-api/revisions/ab03b3c80494/schema)