docs: improve bulk actions docs

docs/bulk-actions.mdx

@@ -1,9 +1,15 @@
 ---
 title: "Bulk actions"
-description: "Perform actions like replay and cancel on multiple runs at once."
+description: "Replay or cancel multiple runs from the dashboard or SDK using filters or selected run IDs."
 ---
 
-Bulk actions allow you to perform replaying and canceling on multiple runs at once. This is especially useful when you need to retry a batch of failed runs with a new version of your code, or when you need to cancel multiple in-progress runs.
+**Bulk actions let you replay or cancel multiple runs asynchronously using the dashboard or SDK.**
+
+Use bulk actions when you need to retry failed runs after deploying a fix, or stop a group of queued or executing runs.
+
+<Note>
+  The dashboard workflow is shown first. For backend code, see [Create a bulk replay from the SDK](#create-a-bulk-replay-from-the-sdk).
+</Note>
 
 <video
   src="https://content.trigger.dev/bulk-actions.mp4"
@@ -16,34 +22,206 @@ Bulk actions allow you to perform replaying and canceling on multiple runs at on
   height="100%"
 />
 
-## How to create a new bulk action
+## Create a bulk action in the dashboard
+
+<Steps>
+  <Step title="Open the bulk action panel">
+    Open the runs page and click **Bulk action** in the top right.
+
+    ![Open the bulk action panel from the runs page](/images/bulk-action-open-panel.png)
+  </Step>
+
+  <Step title="Choose the runs">
+    Filter the runs table to target a group of runs, or select individual runs from the table.
+  </Step>
+
+  <Step title="Configure the action">
+    Choose **Replay** or **Cancel**, add an optional name, then confirm the action.
+
+    ![Configure and create a bulk action](/images/bulk-action-create.png)
+  </Step>
+
+  <Step title="Track progress">
+    Open the bulk action page to see progress, view affected runs, or replay the action.
+
+    ![View bulk action progress](/images/bulk-action-page.png)
+  </Step>
+</Steps>
+
+<Note>
+  You can only cancel runs that are still cancelable, such as queued or executing runs. Runs that have already reached a final state cannot be canceled.
+</Note>
+
+## Create a bulk replay from the SDK
+
+Use `runs.bulk.replay()` to replay every run that matches a filter.
+
+```ts 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 same filters as [`runs.list()`](/management/runs/list), excluding pagination fields. 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.
+</Warning>
+
+<ParamField body="filter" type="BulkActionFilter">
+  Selects runs using the same filter shape as `runs.list()`, excluding `limit`, `after`, and `before`.
+</ParamField>
+
+<ParamField body="runIds" type="string[]">
+  Selects specific run IDs. Provide either `filter` or `runIds`, not both.
+</ParamField>
+
+<ParamField body="name" type="string" optional>
+  A name for the bulk action.
+</ParamField>
+
+<ParamField body="targetRegion" type="string" optional>
+  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()`.
+</ParamField>
+
+## Create a bulk cancel from the SDK
+
+Use `runs.bulk.cancel()` to cancel every run that matches a filter, or specific run IDs.
 
-<Icon icon="circle-1" iconType="solid" color="#FF2D6B" size="20" /> Open the bulk action panel from the top right of the runs page
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
 
-![Access bulk actions](/images/bulk-action-open-panel.png)
+const action = await runs.bulk.cancel({
+  runIds: ["run_1234", "run_5678"],
+  name: "Cancel selected runs",
+});
 
+console.log(action.id);
+```
 
-<Icon icon="circle-2" iconType="solid" color="#FF2D6B" size="20" /> Filter the runs table to show the runs you want to bulk action
+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.
 
-<Icon icon="circle-3" iconType="solid" color="#FF2D6B" size="20" /> Alternatively, you can select individual runs
+## Retrieve progress from the SDK
 
-<Icon icon="circle-4" iconType="solid" color="#FF2D6B" size="20" /> Choose the runs you want to bulk action
+Use `runs.bulk.retrieve()` to read the current status and aggregate counts.
 
-<Icon icon="circle-5" iconType="solid" color="#FF2D6B" size="20" /> Name your bulk action (optional)
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
 
-<Icon icon="circle-6" iconType="solid" color="#FF2D6B" size="20" /> Choose the action you want to perform, replay or cancel
+const action = await runs.bulk.retrieve("bulk_1234");
 
-<Icon icon="circle-7" iconType="solid" color="#FF2D6B" size="20" /> Click the "Replay" or "Cancel" button and confirm in the dialog
+console.log(action.status);
+console.log(action.counts.total, action.counts.success, action.counts.failure);
+```
 
-![Access bulk actions](/images/bulk-action-create.png)
+The returned bulk action object has these fields:
 
-<Icon icon="circle-8" iconType="solid" color="#FF2D6B" size="20" /> You'll now view the bulk action processing from the bulk action page
+<ResponseField name="id" type="string">
+  The bulk action ID, starting with `bulk_`.
+</ResponseField>
 
-<Icon icon="circle-9" iconType="solid" color="#FF2D6B" size="20" /> You can replay or view the runs from this page
+<ResponseField name="type" type="'CANCEL' | 'REPLAY'">
+  The action being performed.
+</ResponseField>
 
-![Access bulk actions](/images/bulk-action-page.png)
+<ResponseField name="status" type="'PENDING' | 'COMPLETED' | 'ABORTED'">
+  The current bulk action status.
+</ResponseField>
+
+<ResponseField name="counts" type="object">
+  Aggregate processing counts.
+
+  <Expandable title="properties">
+    <ResponseField name="total" type="number">
+      The number of runs selected when the bulk action was created.
+    </ResponseField>
+    <ResponseField name="success" type="number">
+      The number of runs processed successfully.
+    </ResponseField>
+    <ResponseField name="failure" type="number">
+      The number of runs that could not be processed.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="createdAt" type="Date">
+  The date and time the bulk action was created.
+</ResponseField>
+
+<ResponseField name="completedAt" type="Date" optional>
+  The date and time the bulk action completed.
+</ResponseField>
+
+## Poll for completion
+
+Use `runs.bulk.poll()` to wait until the bulk action leaves the `PENDING` state.
+
+```ts 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 from the SDK
+
+Use `runs.bulk.abort()` to stop future batches from being processed.
+
+```ts 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.
 
 <Note>
-  You can only cancel runs that are in states that allow cancellation (like QUEUED or EXECUTING).
-  Runs that are already completed, failed, or in other final states by the time the bulk action process gets to them, cannot be canceled.
-</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.
+</Note>
+
+## List bulk actions from the SDK
+
+Use `runs.bulk.list()` to page through previous bulk actions in the current environment.
+
+```ts 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:
+
+```ts 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 bulk action](/management/bulk-actions/create)
+- [List bulk actions](/management/bulk-actions/list)
+- [Retrieve bulk action](/management/bulk-actions/retrieve)
+- [Abort bulk action](/management/bulk-actions/abort)

docs/docs.json

@@ -339,7 +339,6 @@
               "management/runs/retrieve",
               "management/runs/replay",
               "management/runs/cancel",
-              "management/runs/bulk-actions",
               "management/runs/reschedule",
               "management/runs/update-metadata",
               "management/runs/add-tags",
@@ -348,6 +347,15 @@
               "management/runs/retrieve-result"
             ]
           },
+          {
+            "group": "Bulk actions API",
+            "pages": [
+              "management/bulk-actions/create",
+              "management/bulk-actions/list",
+              "management/bulk-actions/retrieve",
+              "management/bulk-actions/abort"
+            ]
+          },
           {
             "group": "Errors API",
             "pages": [
@@ -751,6 +759,14 @@
       "source": "/reattempting-replaying",
       "destination": "/replaying"
     },
+    {
+      "source": "/management/runs/bulk-actions",
+      "destination": "/bulk-actions"
+    },
+    {
+      "source": "/runs/bulk-actions",
+      "destination": "/bulk-actions"
+    },
     {
       "source": "/tasks-overview",
       "destination": "/tasks/overview"

docs/errors-retrying.mdx

@@ -377,3 +377,7 @@ export const openaiTask = task({
   },
 });
 ```
+
+## Replay failed runs in bulk
+
+After you deploy a fix, use [bulk actions](/bulk-actions) to replay multiple failed runs from the dashboard or SDK. Bulk replay creates an asynchronous action that targets selected run IDs or a `runs.list()` filter, so you can retry a known failure set without replaying each run individually.

docs/management/bulk-actions/abort.mdx

@@ -0,0 +1,4 @@
+---
+title: "Abort bulk action"
+openapi: "v3-openapi POST /api/v1/bulk-actions/{bulkActionId}/abort"
+---

docs/management/bulk-actions/create.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create bulk action"
+openapi: "v3-openapi POST /api/v1/bulk-actions"
+---

docs/management/bulk-actions/list.mdx

@@ -0,0 +1,4 @@
+---
+title: "List bulk actions"
+openapi: "v3-openapi GET /api/v1/bulk-actions"
+---

docs/management/bulk-actions/retrieve.mdx

@@ -0,0 +1,4 @@
+---
+title: "Retrieve bulk action"
+openapi: "v3-openapi GET /api/v1/bulk-actions/{bulkActionId}"
+---