---
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

---

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