Skip to content

Commit b4866f0

Browse files
cardernecarderne
authored
docs: improve bulk actions docs (#4211)
- Combine SDK and dashboard bulk actions docs - Fix API reference pages for bulk actions - Fix weird rendering on bulk actions page ## Todo - [ ] not sure about having the SDK+dashboard combined and under "Using the dashboard"... need to find the right place
1 parent e6e8aeb commit b4866f0

9 files changed

Lines changed: 561 additions & 29 deletions

File tree

‎docs/bulk-actions.mdx‎

Lines changed: 46 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
---
22
title: "Bulk actions"
3-
description: "Perform actions like replay and cancel on multiple runs at once."
3+
description: "Replay or cancel multiple runs from the dashboard using filters or selected run IDs."
44
---
55

6-
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.
6+
**Bulk actions let you replay or cancel multiple runs asynchronously from the dashboard.**
7+
8+
Use bulk actions when you need to retry failed runs after deploying a fix, or stop a group of queued or executing runs.
9+
10+
<Note>
11+
For backend code, see [Bulk actions with the SDK](/runs/bulk-actions).
12+
</Note>
713

814
<video
915
src="https://content.trigger.dev/bulk-actions.mp4"
@@ -16,34 +22,55 @@ Bulk actions allow you to perform replaying and canceling on multiple runs at on
1622
height="100%"
1723
/>
1824

19-
## How to create a new bulk action
25+
## Create a bulk action in the dashboard
2026

21-
<Icon icon="circle-1" iconType="solid" color="#FF2D6B" size="20" /> Open the bulk action panel from the top right of the runs page
27+
<Steps>
28+
<Step title="Open the bulk action panel">
29+
Open the runs page and click **Bulk action** in the top right.
2230

23-
![Access bulk actions](/images/bulk-action-open-panel.png)
31+
![Open the bulk action panel from the runs page](/images/bulk-action-open-panel.png)
32+
</Step>
2433

34+
<Step title="Choose the runs">
35+
Filter the runs table to target a group of runs, or select individual runs from the table.
36+
</Step>
2537

26-
<Icon icon="circle-2" iconType="solid" color="#FF2D6B" size="20" /> Filter the runs table to show the runs you want to bulk action
38+
<Step title="Configure the action">
39+
Choose **Replay** or **Cancel**, add an optional name, then confirm the action.
2740

28-
<Icon icon="circle-3" iconType="solid" color="#FF2D6B" size="20" /> Alternatively, you can select individual runs
41+
![Configure and create a bulk action](/images/bulk-action-create.png)
42+
</Step>
2943

30-
<Icon icon="circle-4" iconType="solid" color="#FF2D6B" size="20" /> Choose the runs you want to bulk action
44+
<Step title="Track progress">
45+
Open the bulk action page to see progress, view affected runs, or replay the action.
3146

32-
<Icon icon="circle-5" iconType="solid" color="#FF2D6B" size="20" /> Name your bulk action (optional)
47+
![View bulk action progress](/images/bulk-action-page.png)
48+
</Step>
49+
</Steps>
3350

34-
<Icon icon="circle-6" iconType="solid" color="#FF2D6B" size="20" /> Choose the action you want to perform, replay or cancel
51+
<Note>
52+
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.
53+
</Note>
3554

36-
<Icon icon="circle-7" iconType="solid" color="#FF2D6B" size="20" /> Click the "Replay" or "Cancel" button and confirm in the dialog
3755

38-
![Access bulk actions](/images/bulk-action-create.png)
56+
## Create a bulk action from the SDK
3957

40-
<Icon icon="circle-8" iconType="solid" color="#FF2D6B" size="20" /> You'll now view the bulk action processing from the bulk action page
58+
Use `runs.bulk.replay()` or `runs.bulk.cancel()` when you want to create a bulk action from your backend code.
4159

42-
<Icon icon="circle-9" iconType="solid" color="#FF2D6B" size="20" /> You can replay or view the runs from this page
60+
```ts Your backend code
61+
import { runs } from "@trigger.dev/sdk";
4362

44-
![Access bulk actions](/images/bulk-action-page.png)
63+
const action = await runs.bulk.replay({
64+
filter: {
65+
status: "FAILED",
66+
taskIdentifier: "sync-customer",
67+
period: "24h",
68+
},
69+
name: "Replay failed customer syncs",
70+
});
4571

46-
<Note>
47-
You can only cancel runs that are in states that allow cancellation (like QUEUED or EXECUTING).
48-
Runs that are already completed, failed, or in other final states by the time the bulk action process gets to them, cannot be canceled.
49-
</Note>
72+
const completed = await runs.bulk.poll(action.id);
73+
console.log(completed.status, completed.counts);
74+
```
75+
76+
See [Bulk actions with the SDK](/runs/bulk-actions) for canceling, listing, polling, and aborting bulk actions from your backend code.

‎docs/docs.json‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,8 @@
7777
"run-usage",
7878
"context",
7979
"runs/priority",
80-
"hidden-tasks"
80+
"hidden-tasks",
81+
"runs/bulk-actions"
8182
]
8283
},
8384
{
@@ -339,7 +340,6 @@
339340
"management/runs/retrieve",
340341
"management/runs/replay",
341342
"management/runs/cancel",
342-
"management/runs/bulk-actions",
343343
"management/runs/reschedule",
344344
"management/runs/update-metadata",
345345
"management/runs/add-tags",
@@ -348,6 +348,15 @@
348348
"management/runs/retrieve-result"
349349
]
350350
},
351+
{
352+
"group": "Bulk actions API",
353+
"pages": [
354+
"management/bulk-actions/create",
355+
"management/bulk-actions/list",
356+
"management/bulk-actions/retrieve",
357+
"management/bulk-actions/abort"
358+
]
359+
},
351360
{
352361
"group": "Errors API",
353362
"pages": [
@@ -751,6 +760,10 @@
751760
"source": "/reattempting-replaying",
752761
"destination": "/replaying"
753762
},
763+
{
764+
"source": "/management/runs/bulk-actions",
765+
"destination": "/runs/bulk-actions"
766+
},
754767
{
755768
"source": "/tasks-overview",
756769
"destination": "/tasks/overview"

‎docs/errors-retrying.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -377,3 +377,7 @@ export const openaiTask = task({
377377
},
378378
});
379379
```
380+
381+
## Replay failed runs in bulk
382+
383+
After you deploy a fix, use [bulk actions](/bulk-actions) to replay multiple failed runs from the dashboard, or [bulk actions with the SDK](/runs/bulk-actions) to replay them from backend code. 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‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Abort bulk action"
3+
openapi: "v3-openapi POST /api/v1/bulk-actions/{bulkActionId}/abort"
4+
---

‎docs/management/bulk-actions/create.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Create bulk action"
3+
openapi: "v3-openapi POST /api/v1/bulk-actions"
4+
---

‎docs/management/bulk-actions/list.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "List bulk actions"
3+
openapi: "v3-openapi GET /api/v1/bulk-actions"
4+
---

‎docs/management/bulk-actions/retrieve.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Retrieve bulk action"
3+
openapi: "v3-openapi GET /api/v1/bulk-actions/{bulkActionId}"
4+
---

docs/management/runs/bulk-actions.mdx renamed to docs/runs/bulk-actions.mdx

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
22
title: "Bulk actions"
3-
description: "Cancel or replay many runs from the SDK using run IDs or the same filters as runs.list()."
3+
description: "Cancel or replay many runs from the SDK using run IDs or SDK run-list filters."
44
---
55

6-
**Bulk actions let you cancel or replay many runs asynchronously from the SDK by selecting runs with run IDs or `runs.list()` filters.**
6+
**Bulk actions let you cancel or replay many runs asynchronously from the SDK by selecting runs with run IDs or SDK run-list filters.**
77

88
A bulk action returns a handle immediately. Use the handle to retrieve progress, poll until completion, list previous actions, or abort pending work.
99

@@ -28,18 +28,14 @@ const completed = await runs.bulk.poll(action.id);
2828
console.log(completed.status, completed.counts);
2929
```
3030

31-
`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.
31+
`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.
3232

3333
<Warning>
3434
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.
3535
</Warning>
3636

37-
<Note>
38-
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](#abort-a-bulk-action) one) before starting another. Bulk cancels are not subject to this limit.
39-
</Note>
40-
4137
<ParamField body="filter" type="BulkActionFilter">
42-
Selects runs using the same filter shape as `runs.list()`, excluding `limit`, `after`, and `before`.
38+
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`.
4339
</ParamField>
4440

4541
<ParamField body="runIds" type="string[]">
@@ -148,6 +144,10 @@ await runs.bulk.abort("bulk_1234");
148144

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

147+
<Note>
148+
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.
149+
</Note>
150+
151151
## List bulk actions
152152

153153
Use `runs.bulk.list()` to page through previous bulk actions in the current environment.
@@ -171,3 +171,12 @@ for await (const action of runs.bulk.list({ limit: 25 })) {
171171
console.log(action.id, action.status);
172172
}
173173
```
174+
175+
## API reference
176+
177+
The SDK methods use the bulk actions HTTP API:
178+
179+
- [Create bulk action](/management/bulk-actions/create)
180+
- [List bulk actions](/management/bulk-actions/list)
181+
- [Retrieve bulk action](/management/bulk-actions/retrieve)
182+
- [Abort bulk action](/management/bulk-actions/abort)

0 commit comments

Comments
 (0)