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

package/docs/limits.mdx

@@ -43,7 +43,7 @@ You can request a higher rate limit from us if you're on a paid plan.
 The maximum number of runs that can be queued **per queue** (not across all queues in the environment). Each queue can hold up to its limit independently. When a queue hits its limit, new triggers to that queue are rejected.
 
 <Note>
-  The limits below apply to [Trigger.dev Cloud](https://trigger.dev). If you self-host Trigger.dev, queue size limits are configurable via the `MAXIMUM_DEV_QUEUE_SIZE` and `MAXIMUM_DEPLOYED_QUEUE_SIZE` environment variables — see [Self-hosting environment variables](/self-hosting/env/webapp#run-engine).
+  The limits below apply to [Trigger.dev Cloud](https://trigger.dev). If you self-host Trigger.dev, queue size limits are configurable via the `MAXIMUM_DEV_QUEUE_SIZE` and `MAXIMUM_DEPLOYED_QUEUE_SIZE` environment variables — see [Self-hosting environment variables](/self-hosting/env/webapp).
 </Note>
 
 | Pricing tier | Development (per queue) | Staging / Production (per queue) |
@@ -60,7 +60,7 @@ On Trigger.dev Cloud, all runs have an enforced maximum TTL of 14 days. Runs wit
 
 There is no maximum on `delay`.
 
-If you self-host, you can configure a maximum TTL via the `RUN_ENGINE_DEFAULT_MAX_TTL` environment variable — see [Self-hosting environment variables](/self-hosting/env/webapp#run-engine).
+If you self-host, you can configure a maximum TTL via the `RUN_ENGINE_DEFAULT_MAX_TTL` environment variable — see [Self-hosting environment variables](/self-hosting/env/webapp).
 
 ## Schedules
 
@@ -124,8 +124,6 @@ Payloads and outputs over 512KB are kept in object storage rather than inline. C
 
 A single batch can have a maximum of 1,000 items with SDK 4.3.1+. Prior versions are limited to 500 items.
 
-<SoftLimit />
-
 ## Batch trigger rate limits
 
 Batch triggering uses a token bucket algorithm to rate limit the number of runs you can trigger per environment. Each run in a batch consumes one token.
@@ -154,6 +152,26 @@ When you send a batch trigger, we convert it into individual runs. This limit co
 | Hobby        | 10 concurrent batches |
 | Pro          | 50 concurrent batches |
 
+## Webhook ingest rate limits
+
+Each hosted webhook endpoint accepts a limited number of requests per 10 seconds. Requests over the limit get a `429` response with a `Retry-After` header, and providers that retry deliver them again after the window.
+
+| Pricing tier | Requests per endpoint |
+| :----------- | :-------------------- |
+| Free         | 100 every 10 sec      |
+| Hobby        | 300 every 10 sec      |
+| Pro          | 1,000 every 10 sec    |
+| Enterprise   | Set per organization  |
+
+All of an environment's endpoints also share a per-environment limit, counted in tokens: a request costs one token for every 64 KiB of body, started, so a 10 KiB event costs one and a 1 MiB event costs 16. Requests over it get the same `429` with `Retry-After`.
+
+| Pricing tier | Tokens per environment |
+| :----------- | :--------------------- |
+| Free         | 300 every 10 sec       |
+| Hobby        | 1,000 every 10 sec     |
+| Pro          | 3,000 every 10 sec     |
+| Enterprise   | Set per organization   |
+
 ## Log retention
 
 | Pricing tier | Limit   |
@@ -170,8 +188,8 @@ We limit the size of logs to prevent oversized data potentially causing issues.
 
 #### Attribute Limits
 
-- Span Attribute Count Limit: 256
-- Log Attribute Count Limit: 256
+- Span Attribute Count Limit: 1024
+- Log Attribute Count Limit: 1024
 - Span Attribute Value Length Limit: 131072 characters
 - Log Attribute Value Length Limit: 131072 characters
 
@@ -188,8 +206,8 @@ We limit the size of logs to prevent oversized data potentially causing issues.
 
 #### Attribute Clipping Behavior
 
-- Attributes exceeding the value length limit (1028 characters) are discarded.
-- If the total number of attributes exceeds 256, additional attributes are not included.
+- Attributes exceeding the value length limit (131072 characters) are discarded.
+- If the total number of attributes exceeds 1024, additional attributes are not included.
 
 #### Attribute Value Size Calculation
 

package/docs/logging.mdx

@@ -159,7 +159,7 @@ Trigger.dev automatically collects the following metrics for deployed tasks. No
 | `nodejs.heap.total` | gauge | bytes | V8 heap total |
 
 <Note>
-In dev mode (`trigger dev`), only `process.*` and custom metrics are available.
+In dev mode (`trigger dev`), the `process.*` and `nodejs.*` metrics above are collected, along with custom metrics.
 </Note>
 
 ### Context attributes

package/docs/machines.mdx

@@ -11,7 +11,7 @@ import { task } from "@trigger.dev/sdk";
 export const heavyTask = task({
   id: "heavy-task",
   machine: "large-1x",
-  run: async ({ payload, ctx }) => {
+  run: async (payload, { ctx }) => {
     //...
   },
 });

package/docs/mcp-introduction.mdx

@@ -299,7 +299,7 @@ After adding the config, restart your client. You should see a server named **tr
 
 ## Authentication
 
-The `search_docs` tool works without authentication. All other tools require you to be logged in via the [Trigger.dev CLI](/cli-login-commands). The first time you use an authenticated tool, your MCP client will prompt you to log in.
+The `search_docs` tool works without authentication, and so do the local-only tools `list_profiles`, `dev_server_status` and `stop_dev_server`. All other tools require you to be logged in via the [Trigger.dev CLI](/cli-login-commands). The first time you use an authenticated tool, your MCP client will prompt you to log in.
 
 <Accordion title="CLI Options">
 
@@ -310,7 +310,6 @@ The `install-mcp` command supports these options:
 - `-p, --project-ref <project ref>` — Scope the MCP server to a specific project
 - `-t, --tag <package tag>` — CLI package version to use (default: latest)
 - `--dev-only` — Restrict to the dev environment only
-- `--readonly` — Read-only mode. Hides write tools (`deploy`, `trigger_task`, `cancel_run`) so the AI cannot make changes to your account
 - `--yolo` — Install into all supported clients automatically
 - `--scope <scope>` — `user`, `project`, or `local`
 - `--client <clients...>` — Install into specific client(s)
@@ -341,17 +340,19 @@ Restrict to dev environment for a specific project:
 npx trigger.dev@latest install-mcp --dev-only --project-ref proj_abc123
 ```
 
-Read-only mode (prevents AI from deploying or triggering tasks):
+To add these options to a manual config, append them to the `args` array:
 
-```bash
-npx trigger.dev@latest install-mcp --readonly
+```json
+{
+  "args": ["trigger.dev@latest", "mcp", "--dev-only", "--project-ref", "proj_abc123"]
+}
 ```
 
-To add these options to a manual config, append them to the `args` array:
+The `mcp` command also accepts `--readonly`, which hides the tools that write to your account (for example `deploy`, `trigger_task` and `cancel_run`) so the AI cannot make changes to it. It is only available as a manual config arg:
 
 ```json
 {
-  "args": ["trigger.dev@latest", "mcp", "--dev-only", "--project-ref", "proj_abc123"]
+  "args": ["trigger.dev@latest", "mcp", "--readonly"]
 }
 ```
 

package/docs/mcp-tools.mdx

@@ -102,6 +102,20 @@ Cancel a running or queued run.
 - `"Cancel run run_abc123"`
 - `"Stop that task"`
 
+### replay_run
+
+Replay a run as a new run of the same task, in the same environment. The new run reuses the original run's payload, metadata, tags, queue, concurrency key, and machine unless you override them. See [Replaying](/replaying) for how each option falls back.
+
+**Parameters:**
+- `runId` (required): The run to replay, starting with `run_`
+- `payload`, `metadata`, `tags` (optional): Replace the original run's values
+- `queue`, `concurrencyKey`, `machine`, `version`, `region`, `delay`, `ttl`, `idempotencyKey`, `maxAttempts`, `maxDuration`, `priority` (optional): Override the trigger options for the new run
+
+**Example usage:**
+- `"Replay run run_abc123"`
+- `"Replay that failed run with userId set to user_456"`
+- `"Replay run run_abc123 on a large-1x machine in 10 minutes"`
+
 ## Deployment Tools
 
 ### deploy
@@ -225,7 +239,7 @@ Check the status of the dev server and view recent output. Shows whether it is s
 - `"Are there any build errors?"`
 
 <Callout type="warning">
-  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, and cancel_run.
+  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, and replay_run.
 </Callout>
 
 ## Agent Chat Tools
@@ -317,3 +331,79 @@ Append one record to a named side channel's `in` stream. Sends control input to
 <Callout type="warning">
   `write_session_channel` is a write operation and is not available in readonly mode.
 </Callout>
+
+## Webhook Tools
+
+Set up and debug [hosted webhook endpoints](/webhooks/overview). Endpoint ids start with `wh_` and delivery ids with `whd_`; endpoint tools also accept an endpoint's declared id. The same operations are on the [Webhooks API](/management/webhooks/list-endpoints).
+
+### list_webhook_endpoints
+
+List the environment's webhook endpoints: each one's id, declared id, source, status, URL and whether its signing secret is set.
+
+**Example usage:**
+- `"Which webhook endpoints do I have in dev?"`
+
+### get_webhook_endpoint_details
+
+Get an endpoint's subscribers, with the filters that decide which events each accepts, and its setup prompt: the steps for registering the endpoint and its signing secret with the provider.
+
+**Parameters:**
+- `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+
+**Example usage:**
+- `"Connect my payments webhook to Stripe"`
+
+### list_webhook_deliveries
+
+List recent deliveries, newest first.
+
+**Parameters:**
+- `endpointId` (optional): only this endpoint's deliveries, by declared id or `wh_` id
+- `status` (optional): only these statuses, such as `["failed", "filtered"]`
+- `period` (optional, default: `7d`): how far back to look
+- `limit` (optional, default: `20`): how many to return, up to 100
+- `cursor` (optional): the cursor from a previous call, for the next page
+
+**Example usage:**
+- `"Did the Stripe checkout event arrive in the last hour?"`
+- `"Show me failed deliveries on the github endpoint"`
+
+### get_webhook_delivery
+
+Get one delivery: its status and error, each subscriber's result (the run or session it started, or why its filter skipped the event), how many waiting runs it resumed, and its event and headers.
+
+**Parameters:**
+- `deliveryId` (required): the delivery's `whd_` id
+
+**Example usage:**
+- `"Why didn't this webhook trigger my order task?"`
+
+### replay_webhook_delivery
+
+Replay a delivery from its stored event. Without `targetId` it goes to every subscriber again, with their filters checked again. With `targetId` it goes to that subscriber even if its filter skipped the event.
+
+**Parameters:**
+- `deliveryId` (required): the delivery's `whd_` id
+- `targetId` (optional): the subscriber id to replay to
+
+**Example usage:**
+- `"Replay that delivery to the refunds task"`
+
+### generate_webhook_secret
+
+Generate a new signing secret for an endpoint and return it once, for providers where you choose the secret (such as GitHub). It replaces any existing secret.
+
+**Parameters:**
+- `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+
+### set_webhook_secret
+
+Store a signing secret or public key the provider issued, such as Stripe's `whsec_` secret. It replaces any existing secret.
+
+**Parameters:**
+- `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+- `secret` (required): the secret or public key
+
+<Callout type="warning">
+  `replay_webhook_delivery`, `generate_webhook_secret` and `set_webhook_secret` are write operations and are not available in readonly mode.
+</Callout>

package/docs/migrating-from-v3.mdx

@@ -248,7 +248,7 @@ import { task } from "@trigger.dev/sdk";
 
 export const myTask = task({
   id: "my-task",
-  onStart: ({ payload, ctx }) => {},
+  onStart: (payload, { ctx }) => {},
   run: async (payload, { ctx }) => {},
 });
 ```

package/docs/observability/dashboards.mdx

@@ -98,5 +98,7 @@ There is a separate concurrency limits for metric widgets.
 | Limit                     | Details        |
 | :------------------------ | :------------- |
 | Concurrent widget queries | 30 per project |
+| Custom dashboards         | Free 0, Hobby 1, Pro 5 per organization |
+| Widgets per dashboard     | Free 0, Hobby 10, Pro 20 |
 
 See [Limits](/limits) for details.

package/docs/observability/query.mdx

@@ -8,6 +8,7 @@ description: "Query allows you to write custom queries against your data using T
 - `runs`: contains all task run data including status, timing, costs, and task output. Run metadata (key-value set in your task) is not available on the Query page.
 - `metrics`: contains metrics data for your runs including CPU, memory, and your custom metrics
 - `llm_metrics`: contains LLM/AI metrics including token usage, costs, latency, and model performance data from GenAI spans
+- `llm_models`: anonymized cross-tenant model performance aggregates (calls, cost, latency, throughput per model per minute); it has no tenant-specific data
 
 ### `metrics` table columns
 
@@ -24,6 +25,9 @@ description: "Query allows you to write custom queries against your data using T
 | `machine_name` | string | Machine preset (e.g., `small-1x`) |
 | `worker_version` | string | Worker version |
 | `environment_type` | string | `PRODUCTION`, `STAGING`, `DEVELOPMENT`, `PREVIEW` |
+| `worker_id` | string | Worker ID that produced the metric |
+| `environment` | string | Environment slug |
+| `project` | string | Project ref, starting with `proj_` |
 | `attributes` | json | Raw JSON attributes for custom data |
 
 See [Logging, tracing & metrics](/logging#automatic-system-and-runtime-metrics) for the full list of automatically collected metrics and how to create custom metrics. You can visualize this data on [Dashboards](/observability/dashboards).
@@ -68,7 +72,7 @@ ORDER BY timeBucket
 LIMIT 1000
 ```
 
-Available format types: `bytes`, `percent`, `duration`, `durationSeconds`, `quantity`, `costInDollars`.
+Available format types: `bytes`, `percent`, `duration`, `durationSeconds`, `quantity`, `costInDollars`, `decimalBytes`, `cost`.
 
 ## Using the Query dashboard
 
@@ -602,7 +606,7 @@ LIMIT 100
 
 We have several limits to prevent abuse and ensure performance:
 
-- **Concurrency limit**: We limit the number of concurrent queries per organization.
+- **Concurrency limit**: We limit the number of concurrent queries per project.
 - **Row limit**: We limit the number of rows returned to 10k.
 - **Time restrictions**: We limit the time period you can query.
 - **Time/Memory limit**: We limit the memory a query can use and the time it can run for. As well as other limits like AST complexity.

package/docs/private-networking/aws-console-setup.mdx

@@ -250,7 +250,7 @@ By default, no one can connect to your endpoint service. You need to explicitly
 
     - **Friendly name**: a short, human-readable label for this connection.
     - **VPC Endpoint Service name**: paste the `com.amazonaws.vpce.<region>.vpce-svc-...` value from Step 4.
-    - **Target region**: the AWS region your endpoint service lives in.
+    - **Target region**: the Trigger.dev region where the VPC Endpoint is created (pick one from the list, such as `us-east-1` or `eu-central-1`), normally the region your tasks run in. If it differs from the region your endpoint service lives in, enable cross-region access in Step 3.
 
   </Step>
   <Step title="Submit">

package/docs/private-networking/overview.mdx

@@ -119,7 +119,7 @@ All three conditions must be true. No organization can route traffic to another
 
 ## Limits
 
-- **Two connections per organization.** This is a soft limit — get in touch if you need more.
+- **Four connections per organization.** This is a soft limit — get in touch if you need more.
 - **All ports accepted.** Our security group allows all TCP ports from peered CIDRs. You control which ports are reachable through your NLB and target groups.
 - **Same-region or cross-region.** Connections work within the same region as your tasks or across regions (cross-region adds AWS-level cost and ~10-30ms latency).
 

package/docs/quick-start.mdx

@@ -8,48 +8,11 @@ import CliInitStep from "/snippets/step-cli-init.mdx";
 import CliDevStep from "/snippets/step-cli-dev.mdx";
 import CliRunTestStep from "/snippets/step-run-test.mdx";
 import CliViewRunStep from "/snippets/step-view-run.mdx";
+import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
 
-## Set up with AI
+## Copy the setup prompt
 
-Using an AI coding assistant? Copy this prompt and paste it into Claude Code, Cursor, Copilot, Windsurf, or any AI tool. It'll handle the setup for you.
-
-<Accordion title="Copy the setup prompt">
-
-```text
-Help me add Trigger.dev to this project.
-
-## What to do
-
-1. I need a Trigger.dev account. If I don't have one, point me to https://cloud.trigger.dev to sign up. Wait for me to confirm.
-2. Run `npx trigger.dev@latest init` in the project root.
-   - When it asks about the MCP server, recommend I install it (best DX: gives you direct access to Trigger.dev docs, deploys, and run monitoring).
-   - Install the "Hello World" example task when prompted.
-3. Run `npx trigger.dev@latest dev` to start the dev server.
-4. Once the dev server is running, test the example task from the Trigger.dev dashboard.
-5. Create a named API key in my Development environment with **Trigger only** access. Set it as TRIGGER_SECRET_KEY in my .env file (or .env.local for Next.js).
-6. Ask me what framework I'm using and show me how to trigger the task from my backend code.
-
-If I've already run init and want the MCP server, run: npx trigger.dev@latest install-mcp
-
-## Critical rules
-
-- ALWAYS import from `@trigger.dev/sdk`. NEVER import from `@trigger.dev/sdk/v3`.
-- NEVER use `client.defineJob()` — that's the deprecated v2 API.
-- Use type-only imports when triggering from backend code to avoid bundling task code:
-
-  import type { myTask } from "./trigger/example";
-  import { tasks } from "@trigger.dev/sdk";
-
-  const handle = await tasks.trigger<typeof myTask>("hello-world", { message: "Hello from my app!" });
-
-## When done, point me to
-
-- Writing tasks: https://trigger.dev/docs/tasks/overview
-- Real-time updates: https://trigger.dev/docs/realtime/overview
-- AI tooling: https://trigger.dev/docs/building-with-ai
-```
-
-</Accordion>
+<AgentSetupPrompt />
 
 ## Manual setup
 

package/docs/realtime/auth.mdx

@@ -157,7 +157,7 @@ const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
 
 When you [trigger tasks](/triggering) from your backend, the `handle` received includes a `publicAccessToken` field. This token can be used to authenticate real-time requests in your frontend application.
 
-By default, auto-generated tokens expire after 15 minutes and have a read scope for the specific run(s) that were triggered. You can customize the expiration by passing a `publicTokenOptions` object to the trigger function.
+Auto-generated tokens expire after 1 hour and have a read scope for the specific run(s) that were triggered. For a different expiration or scopes, create a token yourself with [`auth.createPublicToken`](#creating-public-access-tokens).
 
 See our [triggering documentation](/triggering) for detailed examples of how to trigger tasks and get auto-generated tokens.
 

package/docs/realtime/backend/input-streams.mdx

@@ -0,0 +1,159 @@
+---
+title: Input Streams
+sidebarTitle: Input Streams
+description: Send data into running tasks from your backend code
+---
+
+The Input Streams API allows you to send data into running Trigger.dev tasks from your backend code. This enables bidirectional communication — while [output streams](/realtime/backend/streams) let you read data from tasks, input streams let you push data into them.
+
+<Note>
+  To learn how to receive input stream data inside your tasks, see [Input
+  Streams](/tasks/streams#input-streams) in the Streams doc.
+</Note>
+
+<Tip>
+  Input streams are keyed by `runId` — they're correct for sending data to a specific live run. If you need a bidirectional channel that survives run boundaries (e.g. a chat that resumes tomorrow, an agent coordinated across many runs), look at [`chat.agent`](/ai-chat/overview): it's built on a durable Session row that owns its runs and exposes the same consumer-side API (`on` / `once` / `wait` / `waitWithIdleTimeout`) on its `.in` channel.
+</Tip>
+
+## Sending data to a running task
+
+### Using defined input streams (Recommended)
+
+The recommended approach is to use [defined input streams](/tasks/streams#defining-input-streams) for full type safety:
+
+```ts
+import { cancelSignal, approval } from "./trigger/streams";
+
+// Cancel a running AI stream
+await cancelSignal.send(runId, { reason: "User clicked stop" });
+
+// Approve a draft
+await approval.send(runId, { approved: true, reviewer: "alice@example.com" });
+```
+
+The `.send()` method is fully typed — the data parameter must match the generic type you defined on the input stream.
+
+<Note>
+  `.send()` works the same regardless of how the task is listening — whether it uses `.wait()`
+  (suspending), `.once()` (non-suspending), or `.on()` (continuous). The sender doesn't need to know
+  how the task is consuming the data. See [Input Streams](/tasks/streams#input-streams) for details on each
+  receiving method.
+</Note>
+
+## Practical examples
+
+### Cancel from a Next.js API route
+
+```ts app/api/cancel/route.ts
+import { cancelStream } from "@/trigger/streams";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+
+  await cancelStream.send(runId, { reason: "User clicked stop" });
+
+  return Response.json({ cancelled: true });
+}
+```
+
+### Approval workflow API
+
+```ts app/api/approve/route.ts
+import { approval } from "@/trigger/streams";
+
+export async function POST(req: Request) {
+  const { runId, approved, reviewer } = await req.json();
+
+  await approval.send(runId, {
+    approved,
+    reviewer,
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+### Remix action handler
+
+```ts app/routes/api.approve.ts
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+import { approval } from "~/trigger/streams";
+
+export async function action({ request }: ActionFunctionArgs) {
+  const formData = await request.formData();
+  const runId = formData.get("runId") as string;
+  const approved = formData.get("approved") === "true";
+  const reviewer = formData.get("reviewer") as string;
+
+  await approval.send(runId, { approved, reviewer });
+
+  return json({ success: true });
+}
+```
+
+### Express handler
+
+```ts
+import express from "express";
+import { cancelSignal } from "./trigger/streams";
+
+const app = express();
+app.use(express.json());
+
+app.post("/api/cancel", async (req, res) => {
+  const { runId, reason } = req.body;
+
+  await cancelSignal.send(runId, { reason });
+
+  res.json({ cancelled: true });
+});
+```
+
+### Sending from another task
+
+You can send input stream data from one task to another running task:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+import { approval } from "./streams";
+
+export const reviewerTask = task({
+  id: "auto-reviewer",
+  run: async (payload: { targetRunId: string }) => {
+    // Perform automated review logic...
+    const isApproved = await performReview();
+
+    // Send approval to the waiting task
+    await approval.send(payload.targetRunId, {
+      approved: isApproved,
+      reviewer: "auto-reviewer",
+    });
+  },
+});
+```
+
+## Error handling
+
+The `.send()` method will throw if:
+
+- The run has already completed, failed, or been canceled
+- The payload exceeds the 1MB size limit
+- The run ID is invalid
+
+```ts
+import { cancelSignal } from "./trigger/streams";
+
+try {
+  await cancelSignal.send(runId, { reason: "User clicked stop" });
+} catch (error) {
+  console.error("Failed to send:", error);
+  // Handle the error — the run may have already completed
+}
+```
+
+## Important notes
+
+- Maximum payload size per `.send()` call is **1MB**
+- You cannot send data to a completed, failed, or canceled run
+- Data sent before a listener is registered inside the task is **buffered** and delivered when a listener attaches
+- Input streams require the current streams implementation (v2 is the default in SDK 4.1.0+). See [Streams](/tasks/streams) for details.

package/docs/realtime/backend/streams.mdx

@@ -90,18 +90,16 @@ async function consumeWithTimeout(runId: string) {
     timeoutInSeconds: 120, // Wait up to 2 minutes for data
   });
 
-  try {
-    for await (const chunk of stream) {
-      console.log("Received chunk:", chunk);
-    }
-  } catch (error) {
-    if (error.name === "TimeoutError") {
-      console.log("Stream timed out");
-    }
+  for await (const chunk of stream) {
+    console.log("Received chunk:", chunk);
   }
+
+  // The loop ends normally if no data arrives within the timeout
 }
 ```
 
+If no data arrives within `timeoutInSeconds`, the stream closes and the `for await` loop ends without throwing an error. To detect a timeout, track whether you received the chunk you expected to be last.
+
 ### Start index
 
 Resume reading from a specific chunk index (useful for reconnection scenarios):
@@ -122,6 +120,25 @@ async function resumeStream(runId: string, lastChunkIndex: number) {
 }
 ```
 
+### Start from latest
+
+Pass `from: "latest"` to start reading at the end of the stream instead of replaying its history. You may still receive the most recent existing chunk before new chunks arrive. The default is `"beginning"`, which replays the full history first. `from` is ignored when `startIndex` is set:
+
+```ts
+import { streams } from "@trigger.dev/sdk";
+import { aiStream } from "./trigger/streams";
+
+async function watchLive(runId: string) {
+  const stream = await aiStream.read(runId, {
+    from: "latest", // Start at the end of the stream instead of replaying history
+  });
+
+  for await (const chunk of stream) {
+    console.log("Received chunk:", chunk);
+  }
+}
+```
+
 ### Abort signal
 
 Use an `AbortSignal` to cancel stream reading:
@@ -181,8 +198,6 @@ async function advancedStreamConsumption(runId: string) {
   } catch (error) {
     if (error.name === "AbortError") {
       console.log("Stream was cancelled");
-    } else if (error.name === "TimeoutError") {
-      console.log("Stream timed out");
     } else {
       console.error("Stream error:", error);
     }

package/docs/realtime/how-it-works.mdx

@@ -80,7 +80,7 @@ See our [run metadata docs](/runs/metadata) for more on how to write tasks that
 
 You can combine run metadata with the Realtime API to bridge the gap between your trigger.dev tasks and your applications in two ways:
 
-1. Using our [React hooks](/realtime/react-hooks/subscribe#using-metadata) to subscribe to metadata updates and update your UI in real-time.
+1. Using our [React hooks](/realtime/react-hooks/subscribe#using-metadata-to-show-progress-in-your-ui) to subscribe to metadata updates and update your UI in real-time.
 2. Using our [backend functions](/realtime/backend) to subscribe to metadata updates in your backend.
 
 ## Limits

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

@@ -23,7 +23,7 @@ pnpm add @trigger.dev/react-hooks
 ```
 
 ```bash yarn
-yarn install @trigger.dev/react-hooks
+yarn add @trigger.dev/react-hooks
 ```
 
 </CodeGroup>

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

@@ -466,7 +466,7 @@ function MyComponent({ runId, publicAccessToken }: { runId: string; publicAccess
 
 ### Throttling updates
 
-The `useRealtimeRunWithStreams` hook accepts an `experimental_throttleInMs` option to throttle the updates from the server. This can be useful if you are getting too many updates and want to reduce the number of updates.
+The `useRealtimeRunWithStreams` hook accepts a `throttleInMs` option to throttle the updates from the server. This can be useful if you are getting too many updates and want to reduce the number of updates.
 
 ```tsx
 import { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
@@ -480,7 +480,7 @@ export function MyComponent({
 }) {
   const { run, streams, error } = useRealtimeRunWithStreams(runId, {
     accessToken: publicAccessToken,
-    experimental_throttleInMs: 1000, // Throttle updates to once per second
+    throttleInMs: 1000, // Throttle updates to once per second
   });
 
   if (error) return <div>Error: {error.message}</div>;