---
title: "Run Agent"
method: POST
path: "/agents/{agent_id}/run"
tags: ["agents"]
---

# Run Agent

`POST /agents/{agent_id}/run`

Run an agent.

Use `wait=true` to block until the workflow completes (201 Created).
Default (`wait=false`) returns immediately with 202 Accepted.

## Path parameters

- `agent_id` string, required

## Query parameters

- `wait` boolean

## Headers

- `Authorization` string, required

## Request body

- AgentRunRequest — Request to run an agent.
  - `text` string, required — Document text to analyze.
  - `agents` string[], nullable — Agent IDs to execute. Resolved to agent names server-side.
  - `domain_ids` string[], nullable — Terminology domain IDs.
  - `document_ref` string, nullable — Caller-provided document identifier for tracking across scans.
  - `url` string, nullable — Document URL.
  - `document_name` string, nullable — Document name or title.
  - `style_guide_id` string, nullable — Style guide ID to check the document against. ``target_id`` is a deprecated alias for this field; send exactly one of the two names.
  - `content_profile_id` string, nullable — Language-service content profile ID for style checking.
  - `goal` string, nullable — Document goal for agent recommendation.
  - `persona_id` string, nullable — Agent configuration UUID for persona selection. Used by: persona.
  - `voice_profile_id` string, nullable — Agent configuration UUID for brand voice profile selection. Used by: brand_voice.
  - `webhook_url` string, uri, nullable — Optional webhook URL for async result delivery.

## Response `200`

Successful Response

- AgentRunResponse — Response from agent run.
  - `workflow_id` string, required — Workflow ID for tracking
  - `request_id` string, nullable — Request tracking ID
  - `status` 'running' | 'completed' | 'failed' | 'timed_out' | 'cancelled', required — Status of a workflow execution.
  - `document_ref` string, nullable — Caller-provided document identifier.
  - `result` object, nullable — Execution result (if completed)
  - `started_at` string, date-time, required — Workflow start time
  - `completed_at` string, date-time, nullable — Workflow completion time
  - `duration_seconds` number, double, nullable — Execution duration

## Other responses

- `401` — Authentication failed or no valid API key provided.
- `403` — Forbidden
- `422` — Invalid input for agent
- `500` — Workflow execution failed (wait=true)

---

[API](https://skmtc.net/markup/apis/api-reference.md) · [All operations](https://skmtc.net/markup/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/markup/api-reference/revisions/8e28e770c55d/schema)