Skip to main content
Upstash Documentation

Bulk Cancel Messages

Delete all pending messages
2 min read
delete/v2/messages
Request example
Response
delete/v2/messages
Note
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.
Warning

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 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.
  • 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.
Info

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).

Authorization

Authorizationstringheaderrequired#
QStash authentication token

1 alternative authorization method available — see the spec for details.

Query parameters

messageIdsstring[]#
A list of message IDs to delete. If provided, other filters are ignored.
topicNamestring[]#
Filter messages by URL Group name. Supports multiple values.
queueNamestring[]#
Filter messages by Queue name. Supports multiple values.
urlstring[]#
Filter messages by destination URL. Supports multiple values.
hoststring[]#
Filter messages by the host of the destination URL. Supports multiple values.
pathstring[]#
Filter messages by the path of the destination URL. Supports multiple values.
labelstring[]#

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
flowControlKeystring[]#
Filter messages by Flow Control Key. Supports multiple values.
fromDateinteger#
Filter messages created after this timestamp (Unix milli, inclusive).
toDateinteger#
Filter messages created before this timestamp (Unix milli, inclusive).
scheduleIdstring[]#
Filter messages by Schedule ID. Supports multiple values.
callerIpstring[]#
Filter messages by the IP address of the publisher. Supports multiple values.
callerIPstring[]deprecated#
Deprecated. Use callerIp instead.
asyncboolean#
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.

Default: false

countintegerdeprecated#
Deprecated. This parameter is ignored, and all messages matching the filters are cancelled.

Responses

application/json
Messages cancelled, or the bulk action is created when async=true.
cancelledinteger#

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.

actionIdstring#
The ID of the bulk action. Only returned for filter-based cancels with async=true.

Was this page helpful?

Raise issue
Cancel a MessageList Bulk Actions