@trigger.dev/sdk 4.7.3 → 4.7.5

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>;

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