@trigger.dev/sdk 4.7.3 → 4.8.0-webhooks.20261015065339

package/docs/realtime/react-hooks/subscribe.mdx

@@ -119,6 +119,15 @@ export function RunStatusBadge({
 
 You can skip any of: `payload`, `output`, `metadata`, `startedAt`, `delayUntil`, `queuedAt`, `expiredAt`, `completedAt`, `number`, `isTest`, `usageDurationMs`, `costInCents`, `baseCostInCents`, `ttl`, `payloadType`, `outputType`, `runTags`, `error`. The `useRealtimeRunsWithTag` hook also accepts a `skipColumns` option in the same way.
 
+By default the hook stops subscribing once the run completes. Pass `stopOnCompletion: false` to keep receiving updates after completion, for example metadata updates from child runs.
+
+```tsx
+const { run, error } = useRealtimeRun(runId, {
+  accessToken: publicAccessToken,
+  stopOnCompletion: false, // Keep receiving updates after the run completes
+});
+```
+
 See our [run object reference](/realtime/run-object) for the complete schema and [How it Works documentation](/realtime/how-it-works) for more technical details.
 
 ### useRealtimeRunsWithTag
@@ -198,6 +207,14 @@ export function MyComponent({ tag }: { tag: string }) {
 }
 ```
 
+You can also pass an array of tags, and use the `createdAt` option to only subscribe to runs created within a recent period. It accepts a duration string such as `"30m"` or `"1h"` and is applied when the subscription starts. The default and maximum lookback is 24 hours, so longer durations are capped at 24 hours.
+
+```tsx
+const { runs, error } = useRealtimeRunsWithTag(["user:123", "report"], {
+  createdAt: "1h", // Only runs created in the last hour
+});
+```
+
 ### useRealtimeBatch
 
 The `useRealtimeBatch` hook allows you to subscribe to a batch of runs by its the batch ID.
@@ -246,13 +263,12 @@ export function ProgressMonitor({
   runId: string;
   publicAccessToken: string;
 }) {
-  const { run, error, isLoading } = useRealtimeRun(runId, {
+  const { run, error } = useRealtimeRun(runId, {
     accessToken: publicAccessToken,
   });
 
-  if (isLoading) return <div>Loading run...</div>;
   if (error) return <div>Error: {error.message}</div>;
-  if (!run) return <div>Run not found</div>;
+  if (!run) return <div>Loading run...</div>;
 
   const progress = run.metadata?.progress as
     | {

package/docs/realtime/react-hooks/triggering.mdx

@@ -84,8 +84,8 @@ export function MyComponent({ publicAccessToken }: { publicAccessToken: string }
     accessToken: publicAccessToken, // 👈 this is the "trigger" token
   });
 
-  //     use the handle object to preserve type-safety 👇
-  const { run, error: realtimeError } = useRealtimeRun(handle, {
+  //     pass the run ID and the task type to preserve type-safety 👇
+  const { run, error: realtimeError } = useRealtimeRun<typeof myTask>(handle?.id, {
     accessToken: handle?.publicAccessToken,
     enabled: !!handle, // Only subscribe to the run if the handle is available
   });

package/docs/realtime/react-hooks/use-wait-token.mdx

@@ -15,7 +15,7 @@ const token = await wait.createToken({
 
 return {
   tokenId: token.id,
-  publicToken: token.publicAccessToken, // An automatically generated public access token that expires in 1 hour
+  publicToken: token.publicAccessToken, // An automatically generated public access token that expires in 24 hours
 };
 ```
 

package/docs/realtime/run-object.mdx

@@ -36,31 +36,26 @@ Type-safety is supported for the run object, so you can infer the types of the r
   Timestamp when the run was last updated.
 </ParamField>
 
-<ParamField path="number" type="number" required>
-  Sequential number assigned to the run.
-</ParamField>
-
 <ParamField path="status" type="RunStatus" required>
   Current status of the run.
 
   <Accordion title="RunStatus enum">
 
-| Status               | Description                                                                                               |
-| -------------------- | --------------------------------------------------------------------------------------------------------- |
-| `WAITING_FOR_DEPLOY` | Task hasn't been deployed yet but is waiting to be executed                                               |
-| `QUEUED`             | Run is waiting to be executed by a worker                                                                 |
-| `EXECUTING`          | Run is currently being executed by a worker                                                               |
-| `REATTEMPTING`       | Run has failed and is waiting to be retried                                                               |
-| `FROZEN`             | Run has been paused by the system, and will be resumed by the system                                      |
-| `COMPLETED`          | Run has been completed successfully                                                                       |
-| `CANCELED`           | Run has been canceled by the user                                                                         |
-| `FAILED`             | Run has been completed with errors                                                                        |
-| `CRASHED`            | Run has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage |
-| `INTERRUPTED`        | Run was interrupted during execution, mostly this happens in development environments                     |
-| `SYSTEM_FAILURE`     | Run has failed to complete, due to an error in the system                                                 |
-| `DELAYED`            | Run has been scheduled to run at a specific time                                                          |
-| `EXPIRED`            | Run has expired and won't be executed                                                                     |
-| `TIMED_OUT`          | Run has reached it's maxDuration and has been stopped                                                     |
+| Status            | Description                                                                                               |
+| ----------------- | --------------------------------------------------------------------------------------------------------- |
+| `PENDING_VERSION` | Run is waiting for a version update because it cannot execute without additional information              |
+| `QUEUED`          | Run is waiting to be executed by a worker                                                                 |
+| `DEQUEUED`        | Run has been dequeued and is being sent to a worker to start executing                                    |
+| `EXECUTING`       | Run is currently being executed by a worker                                                               |
+| `WAITING`         | Run has been paused by the system, and will be resumed by the system                                      |
+| `COMPLETED`       | Run has been completed successfully                                                                       |
+| `CANCELED`        | Run has been canceled by the user                                                                         |
+| `FAILED`          | Run has been completed with errors                                                                        |
+| `CRASHED`         | Run has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage |
+| `SYSTEM_FAILURE`  | Run has failed to complete, due to an error in the system                                                 |
+| `DELAYED`         | Run has been scheduled to run at a specific time                                                          |
+| `EXPIRED`         | Run has expired and won't be executed                                                                     |
+| `TIMED_OUT`       | Run has reached it's maxDuration and has been stopped                                                     |
 
 </Accordion>
 </ParamField>
@@ -89,10 +84,6 @@ Type-safety is supported for the run object, so you can infer the types of the r
   Timestamp when the run expired.
 </ParamField>
 
-<ParamField path="ttl" type="string">
-  Time-to-live duration for the run.
-</ParamField>
-
 <ParamField path="finishedAt" type="Date">
   Timestamp when the run finished.
 </ParamField>
@@ -121,6 +112,38 @@ Type-safety is supported for the run object, so you can infer the types of the r
   Indicates whether this is a test run.
 </ParamField>
 
+<ParamField path="realtimeStreams" type="string[]" required>
+  Names of the Realtime streams on the run.
+</ParamField>
+
+<ParamField path="isQueued" type="boolean" required>
+  `true` if the run is queued, delayed or waiting for a version update.
+</ParamField>
+
+<ParamField path="isExecuting" type="boolean" required>
+  `true` if the run is dequeued or executing.
+</ParamField>
+
+<ParamField path="isWaiting" type="boolean" required>
+  `true` if the run is waiting.
+</ParamField>
+
+<ParamField path="isCompleted" type="boolean" required>
+  `true` if the run has finished, either successfully or with any failure status.
+</ParamField>
+
+<ParamField path="isFailed" type="boolean" required>
+  `true` if the run failed, crashed, hit a system failure, expired or timed out.
+</ParamField>
+
+<ParamField path="isSuccess" type="boolean" required>
+  `true` if the run completed successfully.
+</ParamField>
+
+<ParamField path="isCancelled" type="boolean" required>
+  `true` if the run was canceled.
+</ParamField>
+
 ## Type-safety
 
 You can infer the types of the run's payload and output by passing the type of the task to the `subscribeToRun` function. This will give you type-safe access to the run's payload and output.

package/docs/replaying.mdx

@@ -49,10 +49,35 @@ export const myTask = task({
 
 You can replay a run using the SDK:
 
-```ts
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
 const replayedRun = await runs.replay(run.id);
+// { id: "run_cmv6ixfn30008ct9kegazjolu" }
 ```
 
+The new run reuses the original run's payload, metadata, tags, queue, concurrency key, and machine. Pass options to override any of them for the new run:
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const replayedRun = await runs.replay(run.id, {
+  payload: { userId: "user_456" },
+  metadata: { source: "replay" },
+  tags: ["replayed"],
+  machine: "large-1x",
+  delay: "10m",
+});
+```
+
+The options use the same names as [`trigger()` options](/triggering): `payload`, `metadata`, `tags`, `queue`, `concurrencyKey`, `machine`, `version`, `region`, `delay`, `ttl`, `idempotencyKey`, `idempotencyKeyTTL`, `maxAttempts`, `maxDuration`, and `priority`. If you leave out `payload`, `metadata`, `tags`, `queue`, `concurrencyKey`, or `machine`, the new run uses the original run's value. The other options fall back to the task's current defaults, and without `version` the replay runs on the current version. The replay always runs in the same environment as the original run.
+
+A `queue` must already exist in the environment, and a `version` must be a version deployed to it. Otherwise the replay fails with an error and no run is created.
+
+A replay starts a new run, so the API key or token you replay with needs permission to trigger the task as well as write access to the run.
+
+The SDK serializes a `payload` override the same way `trigger()` does, so values like `Date`, `BigInt`, `Map` and `Set` reach the task with their types.
+
 When you call `trigger()` or `batchTrigger()` on a task you receive back a run handle which has an `id` property. You can use that `id` to replay the run.
 
 You can also access the run id from inside a run. You could write this to your database and then replay it later.

package/docs/reports.mdx

@@ -123,7 +123,7 @@ The MCP server also registers a `report` prompt, which hosts that support MCP pr
 
 ### HTTP API: `GET /api/v1/reports/:key`
 
-The endpoint behind every surface. It accepts a `period` and a `format`, and authenticates with a token scoped to read the report's query tables (`read:query`).
+The endpoint behind every surface. It accepts a `period` and a `format`, and authenticates with an environment secret key or a JWT scoped to read the report's query tables (`read:query`).
 
 | Query param | Default | Description |
 | --- | --- | --- |
@@ -134,9 +134,11 @@ The endpoint behind every surface. It accepts a `period` and a `format`, and aut
 
 ```bash
 curl "https://api.trigger.dev/api/v1/reports/health?period=24h&format=json" \
-  -H "Authorization: Bearer $TRIGGER_ACCESS_TOKEN"
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
 ```
 
+The environment comes from the key. Use an environment secret key, or a JWT scoped `read:query` for the report's tables. Personal access tokens are not accepted.
+
 An unknown report key returns `404` with the list of available keys.
 
 ## Next steps

package/docs/run-tests.mdx

@@ -7,8 +7,8 @@ You can run a test for any of your tasks, in any environment, from the dashboard
 
 <Note>
   There is no longer a "Test" page in the sidebar. You test a task from the task itself: on the
-  Tasks page open a task (or use the "Test" action next to a task in the Runs list) and press the
-  "Test" button to open its test page.
+  Tasks page use the "Test" action next to a task, or open the task and press "Test task" ("Test
+  schedule" for a scheduled task), to open its test page.
 </Note>
 
 On a task's test page you can:

package/docs/run-usage.mdx

@@ -38,10 +38,10 @@ export const heavyTask = task({
       } 
       */
 
-    // In the cloud product we do not count waits towards the compute cost or duration.
+    // In the cloud product we do not count waits longer than 5 seconds towards the compute cost or duration.
     // We also don't include time between attempts or before the run starts executing your code.
     // So this line does not affect the cost or duration.
-    await wait.for({ seconds: 5 });
+    await wait.for({ seconds: 10 });
 
     // This will give the same result as before the wait.
     currentUsage = usage.getCurrent();
@@ -57,7 +57,7 @@ export const heavyTask = task({
 
 <Note>
   In Trigger.dev cloud we do not include time between attempts, before your code executes, or waits
-  towards the compute cost or duration.
+  longer than 5 seconds towards the compute cost or duration. Waits of 5 seconds or less still count.
 </Note>
 
 ## Getting the run cost and duration from your backend

package/docs/runs/heartbeats.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "Heartbeats"
 description: "Keep long-running or CPU-heavy tasks from being marked as stalled."
 ---
 
-We send a heartbeat from your task to the platform every 30 seconds. If we don't receive a heartbeat within 5 minutes, we mark the run as stalled and stop it with a `TASK_RUN_STALLED_EXECUTING` error.
+We send a heartbeat from your task to the platform every 20 seconds by default for deployed runs (30 seconds in local dev). If we don't receive a heartbeat within 5 minutes, we mark the run as stalled and stop it with a `TASK_RUN_STALLED_EXECUTING` error.
 
 Code that blocks the event loop for too long (for example, a tight loop doing synchronous work on a large dataset) can prevent heartbeats from being sent. In that case, use `heartbeats.yield()` inside the loop so the runtime can yield to the event loop and send a heartbeat. You can call it every iteration; the implementation only yields when needed.
 
@@ -31,7 +31,7 @@ If you see `TASK_RUN_STALLED_EXECUTING`, see [Task run stalled executing](/troub
 
 ## Sending progress to Trigger.dev
 
-To stream progress or status updates to the dashboard and your app, use [run metadata](/runs/metadata). Call `metadata.set()` (or `metadata.append()`) as the task runs. The dashboard and [Realtime](/realtime) (including `runs.subscribeToRun` and the React hooks) receive those updates as they happen. See [Progress monitoring](/realtime/backend/subscribe#progress-monitoring) for a full example.
+To stream progress or status updates to the dashboard and your app, use [run metadata](/runs/metadata). Call `metadata.set()` (or `metadata.append()`) as the task runs. The dashboard and [Realtime](/realtime) (including `runs.subscribeToRun` and the React hooks) receive those updates as they happen. See [Subscribe to metadata updates](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks) for a full example.
 
 ## Sending updates to your own system
 

package/docs/runs/list-best-practices.mdx

@@ -0,0 +1,234 @@
+---
+title: "Using runs.list() efficiently"
+sidebarTitle: "runs.list() best practices"
+description: "When to use runs.list(), the patterns to avoid, and what to use instead."
+---
+
+`runs.list()` (and `GET /api/v1/runs`) is built for browsing, reporting, and bulk operations. It is not a coordination tool. Each call searches your environment's runs in the requested time window, so its cost depends on how many runs you created in that window much more than on the page size you ask for.
+
+A call with `limit: 4` in a busy environment can still search millions of runs to find those 4. That's fine once in a while. On a hot path, like before every trigger or in a loop every second, it slows your own code down and counts against your [API rate limit](/limits).
+
+## Quick reference
+
+| You want to… | Avoid | Use instead |
+| --- | --- | --- |
+| Avoid piling up runs for the same work | `runs.list()` then `trigger()` | [`debounce`](/triggering#debounce) to merge a burst into one run, a [concurrency limit](/concurrency) so runs queue instead of overlapping, or an [`idempotencyKey`](/idempotency) for one run per item |
+| Collapse a burst of triggers into one run | A fixed `delay` on every trigger | [`debounce`](/triggering#debounce) |
+| Avoid duplicate runs for the same work | A random `idempotencyKey` per trigger | A key derived from the work itself |
+| Wait for a run you triggered | Polling `runs.list()` or `runs.retrieve()` | [`triggerAndWait()`](/triggering#yourtask-triggerandwait) inside a task, or [`runs.subscribeToRun()`](/realtime/backend/subscribe) |
+| Follow a group of runs | Polling `runs.list({ tag })` | [`runs.subscribeToRunsWithTag()`](/realtime/backend/subscribe) |
+| Know how backed up a queue is | Counting `QUEUED` runs with `runs.list()` | [`queues.retrieve()`](/queues#retrieving-a-queue) |
+
+## Anti-patterns
+
+### Checking for active runs before triggering
+
+This pattern tries to make sure only one run handles a piece of work at a time:
+
+```ts Avoid
+import { runs, tasks } from "@trigger.dev/sdk";
+
+// Called every time something changes for this account
+export async function onAccountChanged(accountId: string) {
+  const active = await runs.list({
+    status: ["QUEUED", "EXECUTING"],
+    taskIdentifier: ["sync-account"],
+    tag: [`account:${accountId}`],
+    limit: 1,
+  });
+
+  if (active.data.length > 0) return;
+
+  await tasks.trigger(
+    "sync-account",
+    { accountId },
+    { tags: [`account:${accountId}`] }
+  );
+}
+```
+
+It has three problems:
+
+- **It races.** Two calls can both see "nothing running" and both trigger.
+- **It's expensive.** Every change runs a search, and the search gets slower as you create more runs.
+- **It doesn't collapse bursts.** 100 changes in a second still mean 100 searches.
+
+Let Trigger.dev do the coordination instead.
+
+**To collapse bursts into one run, use `debounce`.** While a debounced run is still waiting for its delay, triggers with the same key push it back instead of creating new runs:
+
+```ts Use debounce
+import { tasks } from "@trigger.dev/sdk";
+
+export async function onAccountChanged(accountId: string) {
+  await tasks.trigger(
+    "sync-account",
+    { accountId },
+    {
+      debounce: {
+        key: `account-${accountId}`,
+        delay: "10s",
+        // The run uses the payload of the last trigger
+        mode: "trailing",
+        // Never push it back past 1m after the first trigger
+        maxDelay: "1m",
+      },
+    }
+  );
+}
+```
+
+<Tip>
+  With debounce, one run handles many changes. Have the task read the pending work from your own
+  database when it starts, instead of relying on a single trigger's payload.
+</Tip>
+
+**To never run two at once for the same key, use a per-key concurrency limit.** Extra runs wait in the queue instead of running in parallel:
+
+```ts Use a concurrency limit
+import { task } from "@trigger.dev/sdk";
+
+export const syncAccount = task({
+  id: "sync-account",
+  concurrency: { perKey: 1 },
+  run: async ({ accountId }: { accountId: string }) => {
+    // ...
+  },
+});
+
+// When triggering
+await syncAccount.trigger({ accountId }, { concurrencyKey: accountId });
+```
+
+The `concurrency` option requires SDK 4.7.0 or later. See [Concurrency](/concurrency) for details.
+
+Debounce only merges triggers into a run that hasn't started yet. Once that run is queued or executing, the next trigger creates a new run. Combine both options so bursts collapse and a new run never overlaps one that's still going.
+
+**For exactly one run per piece of work, use an `idempotencyKey`.** See [Using a random idempotency key](#using-a-random-idempotency-key) below.
+
+### Using a fixed delay to space out triggers
+
+Adding the same `delay` to every trigger doesn't collapse anything. Each trigger still creates its own run. It just starts later:
+
+```ts Avoid
+// 100 changes still create 100 runs, each one 30s after its trigger
+await tasks.trigger("sync-account", { accountId }, { delay: "30s" });
+```
+
+Use [`debounce`](#checking-for-active-runs-before-triggering) with the same key instead, so triggers within the delay join one run.
+
+### Using a random idempotency key
+
+An idempotency key only dedupes triggers that send the same key. A fresh random value on every trigger never matches, so every call creates a new run:
+
+```ts Avoid
+await tasks.trigger("sync-account", payload, {
+  // Never matches another trigger, so it dedupes nothing
+  idempotencyKey: `sync-${crypto.randomUUID()}`,
+});
+```
+
+Build the key from the thing that should only happen once:
+
+```ts Your backend
+import { tasks } from "@trigger.dev/sdk";
+
+// One run per change, even if this code runs again within 30 days
+// (the default key lifetime, set with idempotencyKeyTTL)
+await tasks.trigger("process-change", payload, {
+  idempotencyKey: `change-${change.id}`,
+});
+```
+
+<Note>
+  Inside a task, a raw string key is scoped to the current run. To dedupe across runs, create it
+  with `idempotencyKeys.create(key, { scope: "global" })`. See [Idempotency](/idempotency) for
+  scopes and TTLs.
+</Note>
+
+### Polling for a run's status
+
+```ts Avoid
+const handle = await tasks.trigger("generate-report", payload);
+
+while (true) {
+  const run = await runs.retrieve(handle.id);
+  if (run.isCompleted) break;
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+}
+```
+
+Inside a task, use [`triggerAndWait()`](/triggering#yourtask-triggerandwait). You don't pay for compute during waits longer than 5 seconds.
+
+From your backend, subscribe to the run. The loop ends when the run finishes:
+
+```ts Use realtime
+import { runs, tasks } from "@trigger.dev/sdk";
+
+const handle = await tasks.trigger("generate-report", payload);
+
+for await (const run of runs.subscribeToRun(handle.id)) {
+  console.log(run.status);
+}
+```
+
+### Polling runs by tag to follow progress
+
+Calling `runs.list({ tag })` on a timer to see what a user's or a job's runs are doing repeats the same search every time. Subscribe once instead:
+
+```ts Use realtime
+import { runs } from "@trigger.dev/sdk";
+
+const tag = `user:${userId}`;
+
+for await (const run of runs.subscribeToRunsWithTag(tag)) {
+  console.log(run.id, run.status);
+}
+```
+
+This iterator never completes on its own, so break out of the loop when you're done. In a frontend, use the [React hooks](/realtime/react-hooks/overview).
+
+<Note>
+  Tag subscriptions only include runs created in the last 24 hours. You can narrow that with the
+  `createdAt` option, but not extend it. To follow a specific older run, use
+  `runs.subscribeToRun(runId)`.
+</Note>
+
+### Counting runs to measure a backlog
+
+Listing `QUEUED` runs to count them gets slower as the backlog grows, which is exactly when you need the number. It can also miss runs: queued runs created before the [time window](#when-you-do-need-runs-list) aren't returned. The queue already tracks the count:
+
+```ts Use queues.retrieve()
+import { queues } from "@trigger.dev/sdk";
+
+// A task's default queue is named after the task ID
+const queue = await queues.retrieve({
+  type: "task",
+  name: "sync-account",
+});
+
+console.log(queue.queued, queue.running);
+```
+
+For a queue shared between tasks, use `{ type: "custom", name: "your-queue-name" }`.
+
+## When you do need runs.list()
+
+`runs.list()` is the right tool for dashboards, reports, audits, and finding runs to act on in bulk. To keep it fast:
+
+- **Pass a time window.** Use the narrowest `period` (or `from`/`to`) that covers what you need, like `period: "1h"`.
+- **Filter by `taskIdentifier`** as well as status or tag.
+- **Stop paginating once you have what you need.** Don't page through every result by default.
+- **Keep it off hot paths.** Don't call it per event, per trigger, or in a tight loop inside a task. If several places need the same answer, cache it.
+
+<Warning>
+  If you don't pass `period`, `from`, or `to`, only runs created in the last 7 days are searched.
+  The window applies to every status, so runs created before it aren't returned even if they're
+  still queued or executing. Passing only `to` removes the lower bound, so the search covers every
+  run up to that date.
+</Warning>
+
+<Note>
+  If a query would be too expensive to complete, the API returns a `422` asking you to narrow the
+  time window. The SDK doesn't retry it.
+</Note>

package/docs/runs/metadata.mdx

@@ -74,7 +74,7 @@ This means it's safe to call these methods anywhere in your code, and they will
   undefined.
 </Note>
 
-These methods also work inside any task lifecycle hook, either attached to the specific task or the global hooks defined in your `trigger.config.ts` file.
+These methods also work inside any task lifecycle hook, either attached to the specific task or registered globally with `tasks.*` (for example in your `init.ts` file).
 
 <CodeGroup>
 
@@ -86,7 +86,7 @@ export const myTask = task({
   run: async (payload: { message: string }) => {
     // Your run function work here
   },
-  onStart: async () => {
+  onStartAttempt: async () => {
     metadata.set("progress", 0.5);
   },
   onSuccess: async () => {
@@ -95,14 +95,11 @@ export const myTask = task({
 });
 ```
 
-```ts trigger.config.ts
-import { defineConfig, metadata } from "@trigger.dev/sdk";
+```ts init.ts
+import { tasks, metadata } from "@trigger.dev/sdk";
 
-export default defineConfig({
-  project: "proj_1234",
-  onStart: async () => {
-    metadata.set("progress", 0.5);
-  },
+tasks.onStartAttempt(async () => {
+  metadata.set("progress", 0.5);
 });
 ```
 
@@ -731,4 +728,4 @@ See the [API reference](/management/runs/retrieve) for more information.
 
 ## Size limit
 
-The maximum size of the metadata object is 256KB. If you exceed this limit, the SDK will throw an error. If you are self-hosting Trigger.dev, you can increase this limit by setting the `TASK_RUN_METADATA_MAXIMUM_SIZE` environment variable. For example, to increase the limit to 16KB, you would set `TASK_RUN_METADATA_MAXIMUM_SIZE=16384`.
+The maximum size of the metadata object is 256KB. If an update would exceed this limit, the server rejects it (HTTP 413) and the update is not applied. Inside a task, metadata updates are sent in the background, so the SDK logs a `Failed to flush metadata` error instead of throwing from `metadata.set()` or `metadata.flush()`. If you are self-hosting, you can change the limit with the `TASK_RUN_METADATA_MAXIMUM_SIZE` environment variable (bytes, default 262144). For example, to raise it to 512KB, set `TASK_RUN_METADATA_MAXIMUM_SIZE=524288`.

package/docs/runs.mdx

@@ -60,7 +60,7 @@ to complete successfully due to an error in the task code.
 failed because it exceeded its `maxDuration`.
 
 <Icon icon="fire" iconType="solid" color="#E11D48" size={17} /> **Crashed**: The worker process crashed
-during execution (likely due to an Out of Memory error) and won’t be retried.
+during execution (likely due to an Out of Memory error) and won’t be retried, unless `retry.outOfMemory.machine` is set to retry on a larger machine. See [Machines](/machines#retrying-with-a-larger-machine).
 
 <Icon icon="bug" iconType="solid" color="#E11D48" size={17} /> **System failure**: An unrecoverable system
 error has occurred.
@@ -98,7 +98,7 @@ import { runs } from "@trigger.dev/sdk";
 
 const run = await runs.retrieve("run_1234");
 
-if (run.isCompleted) {
+if (run.isSuccess) {
   console.log("Run completed successfully");
 }
 ```
@@ -111,7 +111,7 @@ These helpers are also available when subscribing to Realtime run updates:
 import { runs } from "@trigger.dev/sdk";
 
 for await (const run of runs.subscribeToRun("run_1234")) {
-  if (run.isCompleted) {
+  if (run.isSuccess) {
     console.log("Run completed successfully!");
     break;
   }
@@ -129,7 +129,7 @@ await yourTask.trigger({ foo: "bar" }, { idempotencyKey: "unique-key" });
 ```
 
 - If a run with the same idempotency key is already in progress, the new trigger will be ignored.
-- If the run has already finished, the previous output or error will be returned.
+- If the run completed successfully (or was canceled), the existing run is returned. If it failed or expired, the key is released and triggering again creates a new run.
 
 See our [Idempotency docs](/idempotency) for more information.
 
@@ -253,6 +253,12 @@ Similar to `triggerAndWait()`, the `batchTriggerAndWait()` function lets you bat
 
 #### runs.list()
 
+<Warning>
+  `runs.list()` is for browsing, reporting, and bulk operations, not for coordinating runs. Don't
+  call it before every trigger or poll it in a loop. See [runs.list() best
+  practices](/runs/list-best-practices) for what to use instead.
+</Warning>
+
 List runs in a specific environment. You can filter the runs by status, created at, task identifier, version, and more:
 
 ```ts
@@ -290,7 +296,7 @@ import { runs } from "@trigger.dev/sdk";
 const response = await runs.list({
   status: ["QUEUED", "EXECUTING"], // Filter by status
   taskIdentifier: ["my-task", "my-other-task"], // Filter by task identifier
-  from: new Date("2024-04-01T00:00:00Z"), // Filter by created at
+  from: new Date(Date.now() - 24 * 60 * 60 * 1000), // Filter by created at (last 24 hours)
   to: new Date(),
   version: "20241127.2", // Filter by deployment version,
   tag: ["tag1", "tag2"], // Filter by tags
@@ -327,7 +333,7 @@ If you have just triggered a run, you can pass the entire response object to `re
 import { runs, tasks } from "@trigger.dev/sdk";
 import type { myTask } from "./trigger/myTask";
 
-const response = await tasks.trigger<typeof myTask>({ foo: "bar" });
+const response = await tasks.trigger<typeof myTask>("my-task", { foo: "bar" });
 const run = await runs.retrieve(response);
 
 console.log(run.payload.foo); // string
@@ -346,14 +352,18 @@ await runs.cancel(runId);
 
 #### runs.replay()
 
-Replay a run:
+Replay a run, optionally overriding its payload or options for the new run:
 
 ```ts
 import { runs } from "@trigger.dev/sdk";
 
 await runs.replay(runId);
+
+await runs.replay(runId, { payload: { userId: "user_456" }, delay: "10m" });
 ```
 
+See [Replaying](/replaying#replaying-using-the-sdk) for every option.
+
 #### runs.reschedule()
 
 Updates a delayed run with a new delay. Only valid when the run is in the DELAYED state.
@@ -392,5 +402,5 @@ For more on real-time updates, see the [Realtime](/realtime) documentation.
 
 ### Triggering runs for undeployed tasks
 
-It's possible to trigger a run for a task that hasn't been deployed yet. The run will enter the "Waiting for deploy" state until the task is deployed. Once deployed, the run will be queued and executed normally.
+It's possible to trigger a run for a task that hasn't been deployed yet. The run will enter the "Pending version" state until the task is deployed. Once deployed, the run will be queued and executed normally.
 This feature is particularly useful in CI/CD pipelines where you want to trigger tasks before the deployment is complete.