> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Jobs By Tag V1

> Cancel every live job that matches a tag filter. AND-match: a job must carry every supplied tag to be cancelled…

Cancel every live job that matches a tag filter.

AND-match: a job must carry every supplied tag to be cancelled. Only
queued / running / awaiting\_approval jobs are affected — terminal
jobs are excluded by the SQL filter, regardless of their tags.

Default `dry_run=true` so callers always confirm the count before
issuing a destructive op. Hard cap of 200 cancellations per call to
keep the operation bounded; narrow the filter or call repeatedly if
you legitimately need more.

### Request body

`CancelByTagRequest`

<ParamField body="tags" type="string[]" required>
  Tag values to match — AND-semantics, same as `GET /jobs?tag=`. Up to 10 tags per request.
</ParamField>

<ParamField body="reason" type="string,null">
  Optional reason stamped on every cancelled job.
</ParamField>

<ParamField body="dry_run" type="boolean">
  When true (default), counts what would be cancelled without issuing any cancellations. Always start here; flip to false once the count looks right.
</ParamField>

### Response

`CancelByTagResponse`

<ResponseField name="dry_run" type="boolean" required />

<ResponseField name="matched" type="integer" required />

<ResponseField name="cancelled" type="integer" required />

<ResponseField name="matched_job_ids" type="string[]" required>
  IDs of every live job that matched the tag filter, regardless of dry\_run. Capped at 200 to avoid huge response bodies; if you hit the cap, narrow your tag filter.
</ResponseField>

### Status codes

| Code  | Meaning             |
| ----- | ------------------- |
| `200` | Successful Response |
| `422` | Validation Error    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.computer.stateset.app/api/v1/jobs/cancel-by-tag' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "tags": [
      "priority"
    ],
    "reason": "Two-person tent, green — replacement for damaged pole set.",
    "dry_run": true
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "dry_run": false,
    "matched": 1,
    "cancelled": 1,
    "matched_job_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
  ```
</ResponseExample>