Bulk actions - Trigger.dev

Bulk actions let you cancel or replay many runs asynchronously from the SDK by selecting runs with run IDs or SDK run-list filters. A bulk action returns a handle immediately. Use the handle to retrieve progress, poll until completion, list previous actions, or abort pending work.

Create a bulk replay

Use runs.bulk.replay() to replay every run that matches a filter.

Your backend code

import { runs } from "@trigger.dev/sdk";

const action = await runs.bulk.replay({
  filter: {
    status: "FAILED",
    taskIdentifier: "sync-customer",
    period: "24h",
  },
  name: "Replay failed customer syncs",
  targetRegion: "eu-central-1",
});

const completed = await runs.bulk.poll(action.id);
console.log(completed.status, completed.counts);

filter accepts the SDK run-list filter fields, excluding pagination fields such as limit, after, and before. This is the TypeScript SDK shape used by runs.list() (from, to, and period are top-level fields), not the nested filter[createdAt] query shape shown in the raw HTTP list-runs endpoint. Provide at least one filter field; use runIds when you want to target specific runs. Relative time filters such as period are resolved when the bulk action is created, so later batches process the same fixed time range.

Filters inherit the same time semantics as runs.list(): when you don’t pass from, to, or period, the action defaults to the last 7 days and won’t target older matching runs. To cover a wider range, pass an explicit period (such as "30d"), a from timestamp, or a from/to pair. This default only applies to filter selections; runIds selections are never time-bounded.

filter

BulkActionFilter

Selects runs using the SDK run-list filter shape, excluding limit, after, and before. In raw HTTP requests these fields are sent as JSON body properties, so time fields are top-level (from, to, period) instead of nested under createdAt.

runIds

string[]

Selects specific run IDs. Provide either filter or runIds, not both.

name

string

A name for the bulk action.

targetRegion

string

Replays matching runs in a specific region. When omitted, each replay keeps the original run’s region. This option is only available for runs.bulk.replay().

Create a bulk cancel

Use runs.bulk.cancel() to cancel every run that matches a filter, or specific run IDs.

Your backend code

import { runs } from "@trigger.dev/sdk";

const action = await runs.bulk.cancel({
  runIds: ["run_1234", "run_5678"],
  name: "Cancel selected runs",
});

console.log(action.id);

Only runs that are still cancelable when the action reaches them are canceled. Runs that have already reached a final state count as failures in the bulk action summary.

Retrieve progress

Use runs.bulk.retrieve() to read the current status and aggregate counts.

Your backend code

import { runs } from "@trigger.dev/sdk";

const action = await runs.bulk.retrieve("bulk_1234");

console.log(action.status);
console.log(action.counts.total, action.counts.success, action.counts.failure);

The returned bulk action object has these fields:

string

The bulk action ID, starting with bulk_.

type

'CANCEL' | 'REPLAY'

The action being performed.

status

'PENDING' | 'COMPLETED' | 'ABORTED'

The current bulk action status.

counts

object

Aggregate processing counts.

Show properties

total

number

The number of runs selected when the bulk action was created.

success

number

The number of runs processed successfully.

failure

number

The number of runs that could not be processed.

createdAt

Date

The date and time the bulk action was created.

completedAt

Date

The date and time the bulk action completed.

Poll for completion

Use runs.bulk.poll() to wait until the bulk action leaves the PENDING state.

Your backend code

import { runs } from "@trigger.dev/sdk";

const completed = await runs.bulk.poll("bulk_1234", {
  pollIntervalMs: 2_000,
});

console.log(completed.status);

Abort a bulk action

Use runs.bulk.abort() to stop future batches from being processed.

Your backend code

import { runs } from "@trigger.dev/sdk";

await runs.bulk.abort("bulk_1234");

Abort is best effort. Runs already being processed in the current batch may still finish.

Each environment can only run a limited number of bulk replays at the same time. If you start a replay while too many are still in progress, the call fails and returns an error. Wait for an in-progress replay to finish or abort one before starting another. Bulk cancels are not subject to this limit.

List bulk actions

Use runs.bulk.list() to page through previous bulk actions in the current environment.

Your backend code

import { runs } from "@trigger.dev/sdk";

const page = await runs.bulk.list({ limit: 25 });

for (const action of page.data) {
  console.log(action.id, action.status);
}

List results support the same auto-pagination helpers as other management API list methods:

Your backend code

import { runs } from "@trigger.dev/sdk";

for await (const action of runs.bulk.list({ limit: 25 })) {
  console.log(action.id, action.status);
}

API reference

The SDK methods use the bulk actions HTTP API:

​Create a bulk replay

​Create a bulk cancel

​Retrieve progress

​Poll for completion

​Abort a bulk action

​List bulk actions

​API reference

Create a bulk replay

Create a bulk cancel

Retrieve progress

Poll for completion

Abort a bulk action

List bulk actions

API reference