# Bulk Cancel Workflow Runs

> Cancel all matching workflow runs.

`DELETE /v2/workflows/runs`

<Warning>If you provide a list of workflow run IDs, only those specific workflow runs will be canceled. If you include filter parameters, only the workflow runs matching the filters will be canceled. If no filter or workflow run IDs are sent, all workflow runs will be canceled.</Warning>

Cancelling by `workflowRunIds` is synchronous, and `cancelled` is the exact number of workflow runs cancelled.

A filter-based cancel (including cancelling all workflow runs) is tracked as a [bulk action](/workflow/api-reference/bulk-actions/list-bulk-actions) and runs in the background:

- By default, the request waits up to one minute for the bulk action to finish. If it does not finish in time, a `429` is returned, and the bulk action keeps running in the background.
- With `async=true`, the request returns right after the bulk action is created, together with its `actionId`. You can follow its progress with [Get a Bulk Action](/workflow/api-reference/bulk-actions/get-a-bulk-action).
- `cancelled` is the number of in-progress workflow runs that matched the filters when the request was accepted, not the number of workflow runs actually cancelled.
- Sending the same filters again while an identical bulk action is still in progress does not start a new one. The in-progress bulk action is returned instead.
- Up to 1000 bulk actions can be in progress at the same time. Beyond that, a `412` is returned.

For multi-value filters, a workflow run matches if its value equals any of the given values (OR logic), and multiple filters are combined with AND logic. Multiple values can be passed either by repeating the query parameter (`label=label_1&label=label_2`) or as a single comma-separated value (`label=label_1,label_2`).

## OpenAPI

````yaml workflow/openapi.yaml delete /v2/workflows/runs
openapi: 3.1.0
info:
  title: Upstash Workflow REST API
  description: >
    Upstash Workflow is a serverless workflow orchestration service built on top
    of Upstash QStash and Upstash Redis.
  version: 2.0.0
  contact:
    name: Upstash
    url: https://upstash.com
servers:
  - url: https://qstash-{region}.upstash.io
    description: Regional
    variables:
      region:
        default: eu-central-1
        enum:
          - us-east-1
          - eu-central-1
security:
  - bearerAuth: []
  - bearerAuthQuery: []
paths:
  /v2/workflows/runs:
    delete:
      summary: Bulk Cancel Workflow Runs
      description: Cancel all matching workflow runs.
      tags:
        - Runs
      x-mint:
        content: >
          <Warning>If you provide a list of workflow run IDs, only those
          specific workflow runs will be canceled. If you include filter
          parameters, only the workflow runs matching the filters will be
          canceled. If no filter or workflow run IDs are sent, all workflow runs
          will be canceled.</Warning>


          Cancelling by `workflowRunIds` is synchronous, and `cancelled` is the
          exact number of workflow runs cancelled.


          A filter-based cancel (including cancelling all workflow runs) is
          tracked as a [bulk
          action](/workflow/api-reference/bulk-actions/list-bulk-actions) and
          runs in the background:


          - By default, the request waits up to one minute for the bulk action
          to finish. If it does not finish in time, a `429` is returned, and the
          bulk action keeps running in the background.

          - With `async=true`, the request returns right after the bulk action
          is created, together with its `actionId`. You can follow its progress
          with [Get a Bulk
          Action](/workflow/api-reference/bulk-actions/get-a-bulk-action).

          - `cancelled` is the number of in-progress workflow runs that matched
          the filters when the request was accepted, not the number of workflow
          runs actually cancelled.

          - Sending the same filters again while an identical bulk action is
          still in progress does not start a new one. The in-progress bulk
          action is returned instead.

          - Up to 1000 bulk actions can be in progress at the same time. Beyond
          that, a `412` is returned.


          For multi-value filters, a workflow run matches if its value equals
          any of the given values (OR logic), and multiple filters are combined
          with AND logic. Multiple values can be passed either by repeating the
          query parameter (`label=label_1&label=label_2`) or as a single
          comma-separated value (`label=label_1,label_2`).
      parameters:
        - in: query
          name: workflowRunIds
          required: false
          schema:
            type: array
            items:
              type: string
          description: Optional list of specific workflow run IDs to cancel. If provided,
            the other filters are ignored.
        - in: query
          name: workflowUrl
          required: false
          schema:
            type: array
            items:
              type: string
          description: The URL of the workflow whose runs to cancel. Supports multiple
            values.
        - in: query
          name: workflowUrlExactMatch
          required: false
          schema:
            type: boolean
            default: false
          description: workflow url is searched as a prefix by default. To make it exact
            match, `workflowUrlExactMatch` can be set to true.
        - in: query
          name: fromDate
          required: false
          schema:
            type: number
            format: date-time
          description: Optional start date to filter workflow runs to cancel. Unix
            timestamp in milliseconds.
        - in: query
          name: toDate
          required: false
          schema:
            type: number
            format: date-time
          description: Optional end date to filter workflow runs to cancel. Unix timestamp
            in milliseconds.
        - in: query
          name: callerIp
          required: false
          schema:
            type: array
            items:
              type: string
          description: Optional caller IP address to filter workflow runs to cancel.
            Supports multiple values.
        - in: query
          name: flowControlKey
          required: false
          schema:
            type: array
            items:
              type: string
          description: Optional flow control key to filter workflow runs to cancel.
            Supports multiple values.
        - in: query
          name: label
          required: false
          schema:
            type: array
            items:
              type: string
          description: >
            Optional label to filter workflow runs to cancel. Supports multiple
            values. You can pass multiple values to match workflow runs with any
            of the given labels (OR logic).


            Examples:

            - `label=my_label`

            - `label=label_1&label=label_2`

            - `label=label_1,label_2`
        - in: query
          name: host
          required: false
          schema:
            type: array
            items:
              type: string
          description: Optional host of the workflow URL to filter workflow runs to
            cancel. Supports multiple values.
        - in: query
          name: path
          required: false
          schema:
            type: array
            items:
              type: string
          description: Optional path of the workflow URL to filter workflow runs to
            cancel. Supports multiple values.
        - in: query
          name: async
          required: false
          schema:
            type: boolean
            default: false
          description: >
            Only applies to filter-based cancels. If `true`, the request returns
            as soon as the bulk action is created, without waiting for it to
            finish. The response includes the `actionId` of the bulk action.
        - in: query
          name: count
          required: false
          deprecated: true
          schema:
            type: integer
          description: Deprecated. This parameter is ignored, and all workflow runs
            matching the filters are cancelled.
      responses:
        "200":
          description: Workflow runs cancelled, or the bulk action is created when
            `async=true`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancelled:
                    type: integer
                    description: >
                      When cancelling by `workflowRunIds`, the number of
                      workflow runs cancelled.


                      For filter-based cancels, the number of in-progress
                      workflow runs that matched the filters when the request
                      was accepted.
                  actionId:
                    type: string
                    description: The ID of the bulk action. Only returned for filter-based cancels
                      with `async=true`.
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "412":
          description: Too many bulk actions are in progress. Up to 1000 bulk actions can
            be in progress at the same time.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: The bulk action did not finish within one minute. It keeps running
            in the background and can be tracked via `GET
            /v2/workflows/bulkActions`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: QStash authentication token
    bearerAuthQuery:
      type: apiKey
      in: query
      name: qstash_token
      description: QStash authentication token passed as a query parameter
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
````