---
title: "Cancel a run"
method: POST
path: "/agent/runs/{id}/cancel"
tags: ["Agent"]
---

# Cancel a run

`POST /agent/runs/{id}/cancel`

Cancel a queued or running Agent run. If the run has already reached a terminal status, the API returns the existing run.

## Path parameters

- `id` string, required — Agent run ID. New run IDs are returned with the `agent_run_` prefix.

## Response `200`

Agent run

- AgentRun
  - `id` string, required — Agent run ID. New run IDs are returned with the `agent_run_` prefix.
  - `object` 'agent_run', required
  - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `stopReason` 'schema_satisfied' | 'budget_reached' | 'error' | 'cancelled', required
  - `createdAt` string, date-time, required — When the run was created
  - `completedAt` string, date-time, nullable, required
  - `request` AgentRunRequest, required — Canonicalized request fields stored with the run.
    - `query` string — Natural-language question or instructions for the request.
    - `systemPrompt` string — Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance.
    - `input` object
      - `data` object[] — Records the agent should process or enrich.
      - `exclusion` object[] — Records or entities the agent should avoid returning.
    - `outputSchema` object, nullable — JSON Schema for validated structured output in `output.structured`. Fields unsupported by evidence may be returned as `null`. Supports draft-07, 2019-09, and 2020-12 via `$schema`.
    - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'auto' — Cost and reasoning effort preference for the run. `auto` lets Exa choose the appropriate effort.
    - `previousRunId` string — Agent run ID. New run IDs are returned with the `agent_run_` prefix.
    - `metadata` object — Caller-provided key-value metadata for your own tracking.
    - `dataSources` AgentDataSourceOutput[] — Exa Connect data providers configured for the run.
      - `provider` 'fiber' | 'financial_datasets' | 'similarweb' | 'baselayer' | 'affiliate' | 'particle' | 'jinko', required — Identifier of an Exa Connect data provider.
  - `output` AgentRunOutput, required
    - `text` string, required — Natural-language answer or summary.
    - `structured` union, required — Any JSON value.
      - boolean
      - number
      - string
      - JsonValue[]
      - object
    - `grounding` AgentGrounding[], required — Field-level citations emitted by the run.
      - `field` string, required — Output field the citations support.
      - `citations` AgentCitation[], required
        - `url` string, uri, required — Source URL.
        - `title` string — Source title.
      - `confidence` 'low' | 'medium' | 'high', nullable — Model-reported reliability for this field.
  - `usage` AgentUsage, required
    - `agentComputeUnits` number, required
    - `searches` integer, required
    - `emails` integer, required
    - `phoneNumbers` integer, required
    - `dataSources` AgentDataSourceUsage — Per-provider tool call counts for Exa Connect data sources used during the run. Keys are provider names (e.g. `fiber`, `similarweb`). Only providers with non-zero usage are included.
  - `costDollars` AgentCostDollars, required
    - `total` number, required
    - `agentCompute` number, required
    - `search` number, required
    - `emails` number, required
    - `phoneNumbers` number, required
    - `dataSources` AgentDataSourceCost — Per-provider cost in dollars for Exa Connect data sources used during the run. Keys are provider names (e.g. `fiber`, `similarweb`). Only providers with non-zero usage are included.

## Other responses

- `400` — Invalid request.
- `401` — Team context or authentication was not found.
- `404` — Run not found.
- `429` — Agent run concurrency limit reached.
- `500` — Server error or run timeout.

---

[API](https://skmtc.net/exa/apis/exa-public-api.md) · [All operations](https://skmtc.net/exa/apis/exa-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/exa/exa-public-api/versions/982a352e3781/schema)