> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk actions with the SDK

> Cancel or replay many runs from the SDK using run IDs or SDK run-list filters.

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

```ts Your backend code theme={"theme":"css-variables"}
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.

> [!WARNING]
>
> 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.

```ts Your backend code theme={"theme":"css-variables"}
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.

```ts Your backend code theme={"theme":"css-variables"}
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:

**id** `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.

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

```ts Your backend code theme={"theme":"css-variables"}
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.

```ts Your backend code theme={"theme":"css-variables"}
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.

> [!NOTE]
>
> 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.

```ts Your backend code theme={"theme":"css-variables"}
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:

```ts Your backend code theme={"theme":"css-variables"}
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 bulk action](https://trigger.dev/docs/management/bulk-actions/create.md)
* [List bulk actions](https://trigger.dev/docs/management/bulk-actions/list.md)
* [Retrieve bulk action](https://trigger.dev/docs/management/bulk-actions/retrieve.md)
* [Abort bulk action](https://trigger.dev/docs/management/bulk-actions/abort.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.