---
title: "Cancel a task"
method: POST
path: "/v1/tasks/{task_id}/cancel"
tags: ["tasks"]
---

# Cancel a task

`POST /v1/tasks/{task_id}/cancel`

## Request

- Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.beatra.ai/v1/tasks/{task_id}/cancel`
- Auth: none declared

## Path parameters

- `task_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- TaskCancelRequest
  - `reason` string, nullable

## Response `200`

Already terminal; returns final state (idempotent)

- TaskEnvelope: Standard Task envelope. Returned by every async-creation endpoint, GET /v1/tasks/{id}, and the body of customer callback POSTs.
  - `object` 'task'
  - `task_id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `capability` string, required
  - `workload_type` 'model' | 'social_operation'
  - `model` string, nullable: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks.
  - `resolved_model` string, nullable: Actual model that ran (null until execution starts; equals model for explicit-model calls)
  - `model_selection_reason` unknown
  - `social` SocialTaskIdentity
    - `platform` string, required
    - `operation_key` string, required
    - `operation_name` string, required
    - `schema_hash` string, required
  - `metadata` object, nullable
  - `input` object, nullable
  - `progress` AppApiV1SchemasCommonTaskProgress
    - `percent` integer, nullable
    - `stage` string, nullable
    - `message` string, nullable
  - `output` object, nullable
  - `warnings` TaskWarning[]
    - `code` string, required: e.g. option_clamped / auto_routed
    - `message` string, required
    - `field` string, nullable
  - `error` AppApiV1SchemasCommonTaskError
    - `code` string, required: Stable machine-readable public error code.
    - `type` string, required: Stable public error family.
    - `message` string, required: Human-readable safe failure reason.
    - `retryable` boolean, required: Whether the same logical request may succeed when retried unchanged.
    - `param` string, nullable: JSON Pointer to the relevant request or output field.
    - `details` object, nullable: Provider-neutral expected, received, supported, or candidate failure facts.
    - `request_id` string, required: Request trace identifier for support and correlation.
  - `usage` UsageObject
    - `input_tokens` integer, nullable
    - `output_tokens` integer, nullable
    - `cache_read_tokens` integer, nullable
    - `cache_creation_tokens` integer, nullable
    - `reasoning_tokens` integer, nullable
    - `image_count` integer, nullable
    - `image_pixels` integer, nullable
    - `video_seconds` number, nullable
    - `input_video_seconds` number, nullable: Authoritative input-video seconds included in settled video usage.
    - `output_video_seconds` number, nullable: Authoritative generated/output-video seconds included in settled video usage.
    - `audio_seconds` number, nullable
    - `characters` integer, nullable
    - `lines` UsageLine[]
      - `meter` string, required: e.g. input_token / output_token / image_count / input_video_second / output_video_second
      - `quantity` string, required: Decimal — number of meter units consumed
      - `unit` string, required: Display unit, e.g. 'token' / 'image' / 'second'
      - `billed_amount_credits` string, nullable: Credits charged for this usage line. Populated by PR-2/3.
    - `credits` string, nullable: Credits charged for this Task. Populated by PR-2 / PR-3.
  - `billing` TaskBilling
    - `charged_credits` string, nullable: Credits charged to wallet for this Task. Populated by PR-2/3.
    - `refunded_credits` string, nullable: Credits refunded for this Task. Populated by PR-3.
    - `granted_credits` string, nullable: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied.
    - `grant_source` string, nullable: Which grant covered it. Present exactly when granted_credits is.
    - `net_charged_credits` string, nullable: Final customer charge: charged_credits minus refunded_credits minus granted_credits. This is the number to report as what the Task cost.
  - `callback` TaskCallback
    - `url` string, required
    - `status` 'pending' | 'dispatching' | 'delivered' | 'retrying' | 'failed', required
    - `attempt_count` integer, required
    - `delivered_at` string, date-time, nullable
    - `last_error` string, nullable: Stable Beatra-owned callback delivery failure summary.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `links` TaskLinks, required
    - `self` string, required
    - `cancel` string, nullable
    - `assets` string, nullable: Absolute customer-console URL for viewing and managing the generated artifacts.

## Other responses

- `404`: Not Found
- `409`: Remote execution cannot be confirmed canceled; task continues
- `422`: Validation Error

---

[API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)