# Bulk Cancel Messages
> Delete all pending messages
`DELETE /v2/messages`
Cancelling a message will remove it from QStash and stop it from being delivered in the future. If a message is in flight to your API, it might be too late to cancel.
If you provide a set of message IDs in the request, only those messages will be cancelled.
If you include filter parameters in the request, only the messages that match the filters will be canceled.
If no filter or messageIds are sent, QStash will cancel all of your messages.
Cancelling by `messageIds` is synchronous, and `cancelled` is the exact number of messages cancelled.
A filter-based cancel (including cancelling all messages) is tracked as a [bulk action](/qstash/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](/qstash/api-reference/bulk-actions/get-a-bulk-action).
- `cancelled` is the number of in-progress messages that matched the filters when the request was accepted, not the number of messages 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 message 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 qstash/openapi.yaml delete /v2/messages
openapi: 3.1.0
info:
title: QStash REST API
description: |
QStash is a message queue and scheduler built on top of 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: []
tags:
- name: Messages
description: Publish and manage messages
- name: Queues
description: Manage message queues
- name: Schedules
description: Create and manage scheduled messages
- name: URL Groups
description: Manage URL groups and endpoints
- name: DLQ
description: Dead Letter Queue operations
- name: Logs
description: Log operations
- name: Signing Keys
description: Manage signing keys
- name: Flow Control
description: Monitor flow control keys
- name: Bulk Actions
description: Track filter-based bulk operations
paths:
/v2/messages:
delete:
summary: Bulk Cancel Messages
description: Delete all pending messages
tags:
- Messages
x-mint:
content: >
Cancelling a message will remove it from QStash and stop it from
being delivered in the future. If a message is in flight to your API,
it might be too late to cancel.
If you provide a set of message IDs in the request, only those messages will be cancelled.
If you include filter parameters in the request, only the messages that match the filters will be canceled.
If no filter or messageIds are sent, QStash will cancel all of your messages.
Cancelling by `messageIds` is synchronous, and `cancelled` is the
exact number of messages cancelled.
A filter-based cancel (including cancelling all messages) is tracked
as a [bulk
action](/qstash/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](/qstash/api-reference/bulk-actions/get-a-bulk-action).
- `cancelled` is the number of in-progress messages that matched the
filters when the request was accepted, not the number of messages
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 message 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:
- name: messageIds
in: query
required: false
schema:
type: array
items:
type: string
description: A list of message IDs to delete. If provided, other filters are
ignored.
- name: topicName
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by URL Group name. Supports multiple values.
- name: queueName
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by Queue name. Supports multiple values.
- name: url
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by destination URL. Supports multiple values.
- name: host
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by the host of the destination URL. Supports
multiple values.
- name: path
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by the path of the destination URL. Supports
multiple values.
- name: label
in: query
required: false
schema:
type: array
items:
type: string
description: >
Filter messages by label. Supports multiple values. You can pass
multiple values to match messages with any of the given labels (OR
logic).
Examples:
- `label=my_label`
- `label=label_1&label=label_2`
- `label=label_1,label_2`
- name: flowControlKey
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by Flow Control Key. Supports multiple values.
- name: fromDate
in: query
required: false
schema:
type: integer
description: Filter messages created after this timestamp (Unix milli, inclusive).
- name: toDate
in: query
required: false
schema:
type: integer
description: Filter messages created before this timestamp (Unix milli,
inclusive).
- name: scheduleId
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by Schedule ID. Supports multiple values.
- name: callerIp
in: query
required: false
schema:
type: array
items:
type: string
description: Filter messages by the IP address of the publisher. Supports
multiple values.
- name: callerIP
in: query
required: false
deprecated: true
schema:
type: array
items:
type: string
description: Deprecated. Use `callerIp` instead.
- name: async
in: query
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.
- name: count
in: query
required: false
deprecated: true
schema:
type: integer
description: Deprecated. This parameter is ignored, and all messages matching
the filters are cancelled.
responses:
"202":
description: Messages cancelled, or the bulk action is created when `async=true`.
content:
application/json:
schema:
type: object
properties:
cancelled:
type: integer
description: >
When cancelling by `messageIds`, the number of messages
cancelled.
For filter-based cancels, the number of in-progress
messages 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/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
````