---
title: "Cancel a job"
method: DELETE
path: "/api/jobs/{job_id}"
tags: ["Jobs and downloads"]
---

# Cancel a job

`DELETE /api/jobs/{job_id}`

## Request

- Base URL: `https://epw.tools`
- URL: `https://epw.tools/api/jobs/{job_id}`
- Auth: API key in header `X-API-Key`

Review #82 / D45 — cooperative job cancellation.

Semantics:
  * status=queued   → flip to "cancelled" immediately; worker will
    skip it when picked up.
  * status=running  → set ``cancel_requested=True``; long-running
    compute steps that check the flag will exit early.  Status is
    not flipped here because the worker owns the lifecycle.
  * status=complete | failed | cancelled → 409 Conflict (terminal
    state).  Idempotent re-cancel is intentionally rejected so the
    UI can distinguish "I cancelled this" from "this already
    finished".

Workers can read the flag via
``jobs.get(job_id, {}).get('cancel_requested')`` at checkpoints.

## Path parameters

- `job_id` string, required

## Query parameters

- `key` string, nullable
- `token` string, nullable

## Headers

- `X-API-Key` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `402`: Insufficient credits for this operation.
- `422`: Validation Error
- `429`: Rate limit exceeded — retry after a short delay.

---

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