@trigger.dev/sdk 4.7.3 → 4.7.5

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/max-duration.mdx

@@ -4,6 +4,10 @@ sidebarTitle: "Max duration"
 description: "Set a maximum duration for a task to run."
 ---
 
+Runs have no maximum duration. You set a default `maxDuration` for your project and can override it per task or per run, or set it to `timeout.None` to let a run execute indefinitely.
+
+Trigger is built for long running AI agents and workflows and we have seen Trigger.dev users with runs lasting more than six months.
+
 The `maxDuration` parameter sets a maximum compute time limit for tasks. When a task exceeds this duration, it will be automatically stopped. This helps prevent runaway tasks and manage compute resources effectively.
 
 You must set a default maxDuration in your `trigger.config.ts` file, which will apply to all tasks unless overridden:

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.

package/docs/self-hosting/env/supervisor.mdx

@@ -14,6 +14,7 @@ mode: "wide"
 | `OTEL_EXPORTER_OTLP_ENDPOINT`               | Yes      | —           | OTel exporter endpoint. Point at: `<webapp-url>/otel`       |
 | **Worker instance**                         |          |             |                                                             |
 | `TRIGGER_WORKER_INSTANCE_NAME`              | No       | random UUID | Worker instance name. Set to `spec.nodeName` on k8s.        |
+| `TRIGGER_WORKER_CELL_NAME`                  | No       | —           | Name of the worker cluster this supervisor serves. Stamped on each run it starts. |
 | `TRIGGER_WORKER_HEARTBEAT_INTERVAL_SECONDS` | No       | 30          | Worker heartbeat interval (seconds).                        |
 | **Workload API settings**                   |          |             |                                                             |
 | `TRIGGER_WORKLOAD_API_ENABLED`              | No       | true        | Enable workload API. Runs use this to perform actions.      |
@@ -63,6 +64,8 @@ mode: "wide"
 | **Failed pod handler**                      |          |             |                                                             |
 | `FAILED_POD_HANDLER_ENABLED`                | No       | true        | Enable failed pod handler.                                  |
 | `FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS`  | No       | 1000 (1s)   | Failed pod handler reconnect interval (ms).                 |
+| `FAILED_POD_HANDLER_WATCH_TIMEOUT_SECONDS`  | No       | 300 (5m)    | How long the server keeps each failed pod watch open (s).   |
+| `RUNNER_KILL_REPORTS_ENABLED`               | No       | true        | Fail a run straight away when its pod is killed, as out of memory only if Kubernetes reports `OOMKilled`. |
 | **Debug**                                   |          |             |                                                             |
 | `DEBUG`                                     | No       | false       | Enable debug logs.                                          |
 | `SEND_RUN_DEBUG_LOGS`                       | No       | false       | Send run debug logs to the platform.                        |

package/docs/self-hosting/env/webapp.mdx

@@ -44,6 +44,9 @@ mode: "wide"
 | `WHITELISTED_EMAILS`                             | No       | —                     | Whitelisted emails regex.                                                                                          |
 | `BLOCKED_EMAIL_DOMAINS`                          | No       | —                     | Comma-separated email domains that can't sign in or sign up, including their subdomains.                           |
 | `LOGIN_RATE_LIMITS_ENABLED`                      | No       | true                  | Enable rate limiting on magic-link login.                                                                          |
+| `MAGIC_LINK_SAME_BROWSER_REQUIRED`               | No       | true                  | Only accept a magic link opened in the browser that requested it. Set to false to allow opening it on another device.|
+| `TURNSTILE_SITE_KEY`                             | No       | —                     | Cloudflare Turnstile site key. With `TURNSTILE_SECRET_KEY`, adds a bot check to the magic-link sign-in form.       |
+| `TURNSTILE_SECRET_KEY`                           | No       | —                     | Cloudflare Turnstile secret key, used to verify the check on the server. Turnstile is off unless both keys are set.|
 | `AUTH_GITHUB_CLIENT_ID`                          | No       | —                     | GitHub client ID.                                                                                                  |
 | `AUTH_GITHUB_CLIENT_SECRET`                      | No       | —                     | GitHub client secret.                                                                                              |
 | `CSP_IMG_SRC_ALLOWLIST`                          | No       | —                     | Extra hosts the dashboard may load images from, e.g. an SSO or avatar host serving profile images. A comma-separated list of exact origins (`https://sso.example.com`); a wildcard host such as `https://*.example.com` is refused. |
@@ -98,6 +101,8 @@ mode: "wide"
 | `DEPLOY_REGISTRY_NAMESPACE`                      | No       | trigger               | Deploy registry namespace.                                                                                         |
 | `DEPLOY_REGISTRY_ECR_DEFAULT_REPOSITORY_POLICY`  | No       | —                     | Raw IAM policy JSON applied via SetRepositoryPolicy to every ECR repo created by the webapp. Use to grant cross-account pull access to EKS workers when the ECR account is separate from the cluster account. |
 | `DEPLOY_IMAGE_PLATFORM`                          | No       | linux/amd64           | Deploy image platform, same values as docker `--platform` flag.                                                    |
+| `DEPLOY_BASE_IMAGES`                             | No       | —                     | Base images every deploy must build on, as comma-separated `runtime=image@sha256:<digest>`. See [custom base images](/self-hosting/overview#custom-base-images). |
+| `DEPLOY_BUILD_BASE_IMAGES`                       | No       | —                     | Build-stage images, in the same format as `DEPLOY_BASE_IMAGES`. See [custom base images](/self-hosting/overview#custom-base-images). |
 | `DEPLOY_TIMEOUT_MS`                              | No       | 480000 (8m)           | Deploy timeout (ms).                                                                                               |
 | `DEPLOY_QUEUE_TIMEOUT_MS`                        | No       | 900000 (15m)          | Deploy queue timeout (ms).                                                                                         |
 | **Object store (S3)**                            |          |                       |                                                                                                                    |

package/docs/self-hosting/overview.mdx

@@ -100,6 +100,32 @@ All fields are optional. Partial overrides are supported:
 }
 ```
 
+## Custom base images
+
+Deploys build on the published `triggerdotdev/node` and `triggerdotdev/bun` Debian images. To require a different base for every deploy to your instance, such as a FIPS-validated or hardened Node image, set `DEPLOY_BASE_IMAGES` on the webapp (and optionally `DEPLOY_BUILD_BASE_IMAGES` for the build stage):
+
+```bash
+DEPLOY_BASE_IMAGES="node-26=registry.example.com/node-fips:26@sha256:<64-character-digest>"
+```
+
+Entries are comma-separated `runtime=image@sha256:<digest>`. The runtimes are `node-22`, `node-24`, `node-26` and `bun`, and every image must be pinned by digest. An invalid value prevents the webapp from starting. Projects with `runtime: "node"` in their config resolve to the current default Node runtime (`node-24` today), so set that key for them. With the Helm chart, set the variables through `webapp.extraEnvVars`.
+
+Runtimes with an entry build on that image; the others keep the published images. Deploys from CLI versions that cannot apply the images are rejected with an error asking to upgrade, and so are `--native-build`, `--local-bundle` and `--from-bundle` deploys. This is a self-hosting setting and does not apply to Trigger.dev Cloud.
+
+You own a custom base image. It must provide:
+
+- `node` on `PATH` at the runtime's major version (for `bun`, both `bun` and `node`, because the final stage starts the app with `dumb-init node`)
+- `busybox`, `ca-certificates`, `dumb-init`, `git` and `openssl`
+- a `node` user (a `bun` user for the Bun runtime)
+- glibc, so native modules built in the build stage load at runtime
+
+A `DEPLOY_BUILD_BASE_IMAGES` image needs everything the base image provides, plus `python3`, `make` and `g++`. Build extensions that add image instructions are replayed on it. Without an entry, the build stage uses the published build image, except for projects whose build extensions add image instructions: those build from your base image and install the toolchain with `apt-get`, so that base must be Debian-based. To avoid the published images entirely, set both variables.
+
+<Warning>
+  `image.pkgs` and build extensions that run `apt-get` (such as `aptGet` and `playwright`) assume a
+  Debian base. On other distributions, install those packages in your base image instead.
+</Warning>
+
 ## Community support
 
 It's dangerous to go alone! Join the self-hosting channel on our [Discord server](https://discord.gg/NQTxt5NA7s).

package/docs/tags.mdx

@@ -118,3 +118,9 @@ for await (const run of runs.list({ tag: "user_123456", status: ["COMPLETED"] })
   console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
 }
 ```
+
+<Tip>
+  To follow runs with a tag as they change, use
+  [`runs.subscribeToRunsWithTag()`](/realtime/backend/subscribe) instead of polling `runs.list()`.
+  See [runs.list() best practices](/runs/list-best-practices).
+</Tip>

package/docs/tasks/scheduled.mdx

@@ -45,7 +45,7 @@ export const firstScheduledTask = schedules.task({
     //this can be undefined if you didn't provide one
     console.log(payload.externalId); //is a string or undefined
 
-    //the next 5 dates this task is scheduled to run
+    //the next 10 dates this task is scheduled to run
     console.log(payload.upcoming); //is an array of Date objects
   },
 });
@@ -58,14 +58,14 @@ You can see from the comments that the payload has several useful properties:
 - `timezone` - the timezone the schedule was registered with, defaults to "UTC". In IANA format, e.g. "America/New_York".
 - `scheduleId` - the id of the schedule that triggered the task
 - `externalId` - the external id you (optionally) provided when creating the schedule
-- `upcoming` - the next 5 times the task is scheduled to run
+- `upcoming` - the next 10 times the task is scheduled to run
 
 <Note>
   This task will NOT get triggered on a schedule until you attach a schedule to it. Read on for how
   to do that.
 </Note>
 
-Like all tasks they don't have timeouts, they should be placed inside a [/trigger folder](/config/config-file), and you [can configure them](/tasks/overview#defining-a-task).
+Like all tasks they have a [maxDuration](/runs/max-duration), they should be placed inside a [/trigger folder](/config/config-file), and you [can configure them](/tasks/overview#defining-a-task).
 
 You can set a [TTL](/runs#time-to-live-ttl) on a scheduled task to automatically expire runs that aren't dequeued in time. This is useful when a schedule fires while the previous run is still executing - rather than queueing up stale runs, they'll expire:
 
@@ -142,7 +142,7 @@ To use imperative schedules you need to do two things:
 
 ## Spreading runs with windows
 
-By default a schedule runs at its exact cron time. When many schedules share the same cron pattern, such as a daily `0 9 * * *`, they all fire at the same time and load your downstream systems as well as ours. A **window** spreads those runs out: each schedule is assigned a stable time within the window after its cron time, so the load is smoothed while each schedule keeps firing at a predictable, repeatable moment.
+When many schedules share the same cron pattern, such as a daily `0 9 * * *`, they all fire at the same time and load your downstream systems as well as ours. A **window** spreads those runs out: each schedule is assigned a stable time within the window after its cron time, so the load is smoothed while each schedule keeps firing at a predictable, repeatable moment. New schedules use a [60-minute window by default](#default-window).
 
 The assigned time is deterministic. A given schedule always lands at the same offset for a given interval, so runs don't jump around between occurrences. And you can always see exactly when the next run will start.
 
@@ -151,7 +151,7 @@ Set a `window` as either:
 - **An absolute duration** in whole minutes or hours, up to 24 hours: `"30m"`, `"2h"`, `"24h"`. Absolute windows are capped at the next cron time, so a run is never delayed past its following occurrence.
 - **A percentage** of the interval between runs: `"30%"`, `"100%"`. A `"50%"` window on an hourly schedule spreads runs across the first 30 minutes of each hour.
 
-Set `"0m"` (or `"0%"`) for no spreading — the run fires at its exact cron time.
+Set `"0m"` (or `"0%"`) for no spreading — the run fires at its exact cron time. This also overrides the [default window](#default-window).
 
 Declarative schedules set the window on the `cron` object:
 
@@ -184,6 +184,12 @@ const createdSchedule = await schedules.create({
   is the assigned time the run will actually start.
 </Note>
 
+### Default window
+
+New schedules get a default 60-minute window unless you set one, so each run starts at a stable time within the hour after its cron time. Like any absolute window, it's capped at the next cron time: a schedule that runs every 15 minutes is spread across those 15 minutes.
+
+To opt a new schedule out of the default window, set `window: "0m"`.
+
 ### Free-plan minimum window
 
 Schedules created while an organization is on a free plan run no more than once per hour and use a minimum 60-minute window.

package/docs/triggering.mdx

@@ -746,6 +746,12 @@ await myTask.batchTrigger([{ payload: { some: "data" }, options: { delay: "1h" }
   manually, convert Dates to ISO strings first (e.g., `date.toISOString()`).
 </Note>
 
+<Tip>
+  A `delay` doesn't merge triggers: each trigger still creates its own run. To collapse a burst of
+  triggers into one run, use [`debounce`](#debounce). See [runs.list() best
+  practices](/runs/list-best-practices#using-a-fixed-delay-to-space-out-triggers).
+</Tip>
+
 ### `ttl`
 
 You can set a TTL (time to live) when triggering a task, which will automatically expire the run if it hasn't started within the specified time. This is useful for ensuring that a run doesn't get stuck in the queue for too long.
@@ -814,6 +820,8 @@ export const myTask = task({
 });
 ```
 
+Build the key from the work being done, like an order or event ID. A random value on every trigger never matches, so it never dedupes. See [runs.list() best practices](/runs/list-best-practices#using-a-random-idempotency-key).
+
 For more information, see our [Idempotency](/idempotency) documentation.
 
 ### `idempotencyKeyTTL`