Bulk-cancelling a large backlog of pending runs when auth scoping blocks the API

Last updated: September 28, 2026

Symptom

A deployment accumulates a large backlog of pending runs, for example from a load test or a runaway client, and it overloads an agent or deployment. You want to bulk-cancel or clear the backlog, but your deployment's custom authorization policy scopes threads per end user (derived from the auth token). A single request or token can't reach threads belonging to many different users, so the normal cancel/prune APIs can't clear the whole backlog in one call.

Cause

Agent Server exposes two ways to clear pending runs in bulk:

  • POST /runs/cancel filtering by status: pending

  • POST /threads/prune, which cascades to delete the associated runs

Both are still subject to your deployment's custom authorization filters. A request can only act on the threads and runs its authorization context is permitted to see. If threads are scoped one-per-user and your auth context only covers a single user's threads, neither endpoint can touch other users' threads in the same call, since the authorization handler blocks access outside that scope.

Resolution

If your authorization policy can grant a context broad enough to cover all the threads you need to clear, use the supported, non-destructive endpoint:

POST /runs/cancel
{"status": "pending"}

This defaults to action=interrupt. The status filter applies to every pending run visible to that request's authorization scope, not just the runs from one overloaded agent or graph, so confirm the scope before running it against a large backlog.

If authorization scoping blocks a broad-enough context from using either endpoint, clear the backlog directly at the data layer instead, in this order:

  1. Delete the affected rows from the runs table.

  2. Delete the corresponding Redis run-queue key (named {prefix}run:queue:threads, or {prefix}run:{queue}:threads if you're using a Redis queue configuration) so the queue worker stops churning through queue entries for runs that no longer exist.

Deleting rows directly bypasses the normal cancellation path, which also records cancellation intent and signals workers. If you skip clearing the matching Redis queue entries, the queue worker still attempts to process the now-deleted queue entries, so do both steps together.

References