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

# Cancel agent run

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

## Request

- Base URL: `https://developer.qaip.com/api/v1`
- URL: `https://developer.qaip.com/api/v1/agent/runs/{run_id}/cancel`
- Auth: API key in header `x-api-key`

Start asynchronous cancellation. A running AgentCore session enters CANCELLING until StopRuntimeSession is confirmed or the bounded stop policy records a terminal failure.

Required scope: \`inference:run\`

## Path parameters

- `run_id` string, required

## Query parameters

- `principal_id` string

## Response `202`

Cancellation accepted. Active runs are returned in CANCELLING state.

- AgentRun
  - `run_id` string, required
  - `thread_id` string, required
  - `workflow_type` string, required
  - `provider` 'ANTHROPIC_DIRECT' | 'BEDROCK' | 'OPENAI' | 'VERTEX_AI', required
  - `execution_mode` 'LOCAL' | 'AGENTCORE', required
  - `status` 'QUEUED' | 'RUNNING' | 'CANCELLING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', required: Agent run lifecycle state.
  - `runtime_arn` string, nullable
  - `mcp_session_id` string, nullable
  - `trace_id` string, nullable: 保存済みW3C trace contextから導出したlowercase OpenTelemetry trace ID。移行前の行はnull。
  - `request_id` string, nullable: Correlation ID of the first request that created this run. For HTTP creation it matches that request's X-Request-ID. Idempotent retries and later reads preserve this value even though their own HTTP response headers carry different request IDs. Runs created before correlation recording was introduced return null. Direct service callers without an HTTP request receive a generated correlation ID.
  - `idempotency_key` string, nullable
  - `created_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `input` object, nullable: Server-enriched agent input used to reconstruct the thread transcript.
  - `parent_run_id` string, nullable: Run this run branched from within the thread (null for the thread root).
  - `input_history_mode` 'legacy_full' | 'delta_v1', required: How the request supplied conversation history for this run.
  - `context_start_run_id` string, nullable, required: Oldest run included in the reconstructed rolling context, or null when none was needed.
  - `context_truncated` boolean, required: Whether older turns were omitted to stay within the server context budget.
  - `result` object, nullable
  - `error` object, nullable

## Other responses

- `401`: Unauthorized
- `404`: Not Found
- `502`: The application proxy could not obtain an upstream response before forwarding response headers. The error code is unavailable and retryable is false: upstream side effects may have completed, so a 502 alone does not make retrying safe. Check the operation's idempotency and recovery contract before retrying. A failure after streaming has started instead aborts the stream without appending this JSON body. CDN or load-balancer generated errors may have a different body and are not described by this response.

## Changes

- **2026-09-17** `2489c6f1a9d8`: 10 info
  - added the non-success response with the status `502`
  - added the optional property `error/code` to the response with the `401` status
  - added the optional property `error/code` to the response with the `404` status
  - added the optional property `error/details` to the response with the `401` status
  - …6 more
- **2026-09-01** `b065e544fec5`: 1 warning, 4 info
  - added the new `OPENAI` enum value to the `provider` response property for the response status `202`
  - the `trace_id` response's property pattern `^[0-9a-f]{32}$` was added for the status `202`
  - added the required property `context_start_run_id` to the response with the `202` status
  - added the required property `context_truncated` to the response with the `202` status
  - …1 more
- **2026-09-01** `26fef6564ef0`: 3 breaking, 2 info
  - removed the required property `context_start_run_id` from the response with the `202` status
  - removed the required property `context_truncated` from the response with the `202` status
  - removed the required property `input_history_mode` from the response with the `202` status
  - removed the `OPENAI` enum value from the `provider` response property for the response status `202`
  - …1 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/qlonolink/apis/qaip-apis/changes/agent/runs/:run_id/cancel/post.md)

---

[API](https://skmtc.dev/qlonolink/apis/qaip-apis.md) - [All operations](https://skmtc.dev/qlonolink/apis/qaip-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/qlonolink/apis/qaip-apis/revisions/2489c6f1a9d8?raw)