---
title: "Run an agent"
method: POST
path: "/agents/{id}/runs"
---

# Run an agent

`POST /agents/{id}/runs`

Triggers a run of the agent immediately, regardless of its cadence or active flag. The run is created `pending` and executed asynchronously — poll `GET /agents/{id}/runs/{run_id}` for status, summary, and output files.

## Path parameters

- `id` string, required

## Response `201`

Run created and queued

- AgentRun — One execution of an agent. Unset fields (e.g. error_message on a successful run) are omitted from responses.
  - `id` string, uuid
  - `scheduled_agent_id` string, uuid — The agent this run belongs to
  - `triggered_by` 'manual' | 'schedule' | 'resume' | 'drop' | 'api' — `api` for runs started through this API
  - `triggered_by_user_id` string, nullable — The user who started a manual run; null for API-triggered runs
  - `agent_review_task_id` string, nullable — For resume runs: the review task whose resolution this run executes
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `duration_ms` integer, nullable
  - `error_message` string, nullable
  - `summary` string, nullable — The agent's markdown summary of what it did
  - `model` string, nullable — The model this run executed on
  - `total_input_tokens` integer, nullable
  - `total_output_tokens` integer, nullable
  - `output_files` AgentFile[] — Files the agent produced for the operator
    - `id` string, uuid
    - `filename` string
    - `byte_size` integer
    - `content_type` string
    - `created_at` string, date-time
    - `url` string — Signed download path, relative to the API host
  - `dropped_files` AgentFile[] — For drop runs: the file(s) this run was triggered to process
    - `id` string, uuid
    - `filename` string
    - `byte_size` integer
    - `content_type` string
    - `created_at` string, date-time
    - `url` string — Signed download path, relative to the API host
  - `delivery` object, nullable — The email delivery record for this run's output files, when delivery ran
  - `transcript` object[] — Full event transcript. Only included when fetching a single run
  - `created_at` string, date-time

## Other responses

- `401` — Unauthorized
- `403` — Forbidden — agent management requires a standard API key
- `404` — Agent not found

---

[API](https://skmtc.dev/endclose/apis/end-close-api.md) · [All operations](https://skmtc.dev/endclose/apis/end-close-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/endclose/end-close-api/revisions/2e572738191a/schema)