---
title: "Run an agent, paid per run via x402"
method: POST
path: "/v1/agents/{id}/run"
---

# Run an agent, paid per run via x402

`POST /v1/agents/{id}/run`

## Request

- Base URL: `https://agents.dexl.io`
- URL: `https://agents.dexl.io/v1/agents/{id}/run`
- Auth: API key in header `X-Payment`

The agent reasons, calls its tools when it needs them, and answers. Price is quoted against the worst case: every step it is allowed to take, at its full token ceiling. Send without payment to receive the exact amount in the 402.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `input` string, required: The task for the agent

## Response `200`

The run finished. Check `status`: a failed run still returns 200 because payment was taken and work was done.

- object
  - `id` string: Run id
  - `object` string
  - `agent_id` string
  - `request_id` string
  - `status` 'succeeded' | 'failed' | 'max_steps'
  - `output` string, nullable
  - `steps` object[]
    - `index` integer
    - `kind` 'model' | 'tool'
    - `ref` string
    - `status` string
    - `cost_usd` number
    - `latency_ms` integer
  - `usage` object
    - `steps` integer
    - `tool_calls` integer
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
  - `cost` object
    - `provider_usd` number
    - `tool_usd` number
    - `charged_usd` number

## Other responses

- `402`: Payment required - the exact price is in the PAYMENT-REQUIRED header
- `404`: No such agent - no payment was taken
- `409`: The agent is not active, or an identical Idempotency-Key is still running
- `422`: This Idempotency-Key was used with a different body
- `429`: Rate limited

---

[API](https://skmtc.dev/dexl/apis/dexl-agents.md) · [All operations](https://skmtc.dev/dexl/apis/dexl-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/dexl/apis/dexl-agents/revisions/e3692765c3f7?raw)