---
title: "Run the agent graph"
method: POST
path: "/api/v1/agents/run"
tags: ["agents"]
---

# Run the agent graph

`POST /api/v1/agents/run`

## Request

- Base URL: `https://api.cadencz.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cadencz.com/api/v1/agents/run`
- Auth: HTTP bearer

Executes the Cadencz agent graph for one request and returns the run with its full per-agent trace. Phase A route is 'answer' (a strict one-line assistant).

## Request body

- AgentRunRequest
  - `input` string, required: What the user is asking the agent graph to do.
  - `tags` string[]: Strict allow-list tags that steer the graph (e.g. #reddit, #hook, #shorten).
  - `platform` string, nullable: Optional target platform for this run.
  - `brain_id` string, nullable: Optional Brain id/slug to ground the run in saved product knowledge.
  - `route` string: Graph route: 'answer' (strict one-line) or 'generate_post'.
  - `read_source` string: Reader source: 'paste' | 'rss' | 'x' (x is flagged off in v1).
  - `read_input` string, nullable: Optional material for the Reader agent — pasted text or an RSS URL.

## Response `200`

Successful Response

- AgentRunRead
  - `id` string, required
  - `workspace_id` string, required
  - `route` string, required: The graph route (stored as the run 'stage').
  - `status` string, required
  - `tags` string[], required
  - `input_text` string, nullable, required
  - `output_json` object, required
  - `error` string, nullable, required
  - `tokens_used` integer, required
  - `model_provider` string, nullable, required
  - `model_name` string, nullable, required
  - `steps` AgentStepRead[], required
    - `id` string, required
    - `sequence` integer, required
    - `agent_name` string, required
    - `tier` string, required
    - `provider` string, nullable, required
    - `model` string, nullable, required
    - `status` string, required
    - `attempt` integer, required
    - `output_json` object, required
    - `error` string, nullable, required
    - `input_tokens` integer, nullable, required
    - `output_tokens` integer, nullable, required
    - `total_tokens` integer, nullable, required
    - `cached_input_tokens` integer, nullable, required
    - `latency_ms` integer, nullable, required
    - `created_at` string, date-time, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `401`: Missing or invalid Supabase bearer token.
- `422`: Validation Error
- `502`: The upstream provider rejected the request.
- `503`: Required infrastructure or provider config is unavailable.

---

[API](https://skmtc.dev/cadencz/apis/cadencz-api.md) · [All operations](https://skmtc.dev/cadencz/apis/cadencz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cadencz/apis/cadencz-api/revisions/3392fe5e93db?raw)