@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/reports.mdx

@@ -0,0 +1,159 @@
+---
+title: "Project health report"
+sidebarTitle: "Health report"
+description: "Get a deterministic verdict on your project's health — split into Flow, Execution, and Liveness — from the CLI, an MCP tool or prompt, or the HTTP API."
+---
+
+**The health report answers one question — "is my project healthy, and if not, is the problem my code or the platform?" — with a deterministic verdict, not a dashboard.** The server computes the verdict from your telemetry; no LLM interprets it, so the same numbers always produce the same answer.
+
+Every report reads a live window of your project's data and returns a headline verdict, the evidence behind it, and a single suggested next action. The only report today is `health`.
+
+## What the report measures
+
+The report splits a project into three dimensions, each with its own verdict:
+
+| Dimension | Question | What a bad verdict means |
+| --- | --- | --- |
+| **Flow** | Is work starting? | Runs are queuing but not being picked up — a concurrency limit, a throttle, or a trigger spike. |
+| **Execution** | Are the runs that start succeeding? | Runs are failing or slowing more than your baseline — usually your code. |
+| **Liveness** | Is the telemetry fresh? | The data behind the report is stale, so the verdict can't be trusted. |
+
+Splitting Flow from Execution is the point: a project can be failing to _start_ work (Flow) while every run that does start _completes_ fine (Execution), or the reverse. The report names which one, so you know whether to look at your concurrency settings or your task code.
+
+Each dimension carries a severity — healthy, degraded, or failing — and the report leads with the worst one as its headline. The headline finding is expanded with its supporting metrics; the others collapse to a one-line verdict.
+
+## Reading the report
+
+Here is `trigger report health` for a project whose runs are backing up against the environment concurrency limit:
+
+```text
+/report health        prod · last 1h · vs 7d normal
+
+✕ Flow stalled — at your env concurrency limit for the last 40 min
+
+  concurrency     100/100           ▄▅▆▇████   40 min at limit
+  pending         1,240      ↑ 6×   ▁▂▄▅▆▇██   (normal ~120)
+  start latency   p95 8.2s   ↑ 4×   ▁▂▃▄▆▇██   (normal ~2s)
+
+  why:  runs are finishing at ~90/min
+        nothing dead-lettered
+
+✓ EXECUTION   runs are executing normally
+
+✓ LIVENESS    fresh — telemetry current, updated 12s ago
+
+  read: limit saturated → incoming work exceeds capacity → backlog grows
+
+→ Raise the env concurrency limit
+  Read concurrency docs
+  or do nothing — backlog drains in ~26.7 min once triggers ease
+```
+
+The verdict reads top to bottom:
+
+- **Headline** — the worst finding, stated as a verdict with the breach window. Here Flow is stalled because concurrency has been pinned at its limit for 40 minutes.
+- **Evidence** — the metrics behind the headline, each with a sparkline over the window, its movement against your baseline (`↑ 6×` means six times normal), and an annotation (`40 min at limit`) or baseline (`normal ~120`).
+- **`why:`** — the facts that support the verdict, including what the problem _isn't_ (runs are still finishing, nothing is dead-lettered — so it's not your code).
+- **Sibling findings** — Execution and Liveness, each a one-line verdict.
+- **`read:`** — the causal chain in one line.
+- **Next steps** — the primary action first (`→`), then any alternatives.
+
+### The verdict vocabulary
+
+Every surface carries meaning in glyphs, never color alone, so the report is legible in a monochrome terminal or a plain-text MCP host:
+
+| Glyph | Meaning |
+| --- | --- |
+| `✓` | Healthy |
+| `⚠` | Degraded |
+| `✕` | Failing |
+| `○` | Genuinely unknown — neither good nor bad |
+| `⚑` | The data behind the report can't be trusted |
+| `↑` `↓` `→` | Above, below, or flat against the baseline |
+
+<Note>
+  The markdown surface swaps the status glyphs for traffic-light emoji (`🟢` `🟡` `🔴` `⚪` `🚩`) — the one color cue a chat host that renders neither ANSI nor HTML can show. The glyph and the emoji mean the same thing.
+</Note>
+
+## Surfaces
+
+The same report renders four ways.
+
+### CLI: `trigger report`
+
+Print an interpreted report for an environment. The command defaults to the `health` report and the `prod` environment — a manual production check.
+
+```bash
+npx trigger.dev@latest report health --env prod --period 24h
+```
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `[key]` | `health` | The report to render (positional argument). |
+| `-e, --env` | `prod` | The environment: `dev`, `staging`, `prod`, or `preview`. |
+| `-b, --branch` | — | The preview branch. Required when `--env preview`. |
+| `--period` | `1h` | The live window: `30m`, `1h`, `24h`, `7d`. Minutes to weeks, max 90 days. |
+| `-p, --project-ref` | from config | The project ref (`proj_…`). Required if there is no `trigger.config.ts`. |
+| `-c, --config` | — | Path to the config file. |
+
+The command prints only the report — no banner — so it pipes cleanly. Output is ANSI-colored in a real terminal and plain markdown when piped:
+
+```bash
+trigger report health > health.md   # markdown, no escape codes
+```
+
+Color follows the [supports-color](https://github.com/chalk/supports-color) convention: `NO_COLOR` (any value) or `FORCE_COLOR=0` disables color outright; `FORCE_COLOR` set to anything else force-enables it. Both win over TTY detection — which matters for agents spawned on a PTY, where `isTTY` is `true` but escape codes would be garbled.
+
+### MCP tool: `get_report`
+
+Fetch the report from an AI coding tool through the [Trigger.dev MCP server](/mcp-introduction). The tool returns plain markdown by default, or ANSI when `color` is set (for hosts that display escapes in tool output). It is read-only.
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `key` | — | The report to render. Currently only `health`. |
+| `environment` | `dev` | The environment. The MCP server is dev-centric, so an unspecified environment reports on `dev` — pass `environment` explicitly to report on production. |
+| `period` | `1h` | Time window shorthand, e.g. `1h`, `24h`, `7d`. |
+| `color` | `false` | Return ANSI-colored text instead of markdown. |
+| `projectRef` | auto-detected | The project ref. Detected from `trigger.config.ts` if present. |
+| `branch` | — | The preview branch, for preview or branchable dev environments. |
+
+### MCP prompt: `/report`
+
+The MCP server also registers a `report` prompt, which hosts that support MCP prompts surface as a slash command (Claude Code renders it as `/mcp__trigger__report`). Running `/report health` calls `get_report` for you and shows the result verbatim in a fenced code block, preserving the monospace alignment and sparklines.
+
+### HTTP API: `GET /api/v1/reports/:key`
+
+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 |
+| --- | --- | --- |
+| `period` | `1h` | The live window, same grammar as the CLI. |
+| `format` | `markdown` | `markdown`, `ansi`, or `json`. |
+
+`format=markdown` and `format=ansi` return the rendered text. `format=json` returns the `ReportViewModel` — the semantic payload behind the render, where verdicts are codes rather than prose, for building your own surface on top of the report.
+
+```bash
+curl "https://api.trigger.dev/api/v1/reports/health?period=24h&format=json" \
+  -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
+
+<CardGroup cols={2}>
+  <Card title="MCP server" icon="plug" href="/mcp-introduction">
+    Connect your AI coding tool to Trigger.dev.
+  </Card>
+  <Card title="MCP tools" icon="wrench" href="/mcp-tools">
+    Every tool the MCP server exposes, including `get_report`.
+  </Card>
+  <Card title="Concurrency" icon="layer-group" href="/concurrency">
+    Configure the concurrency limits the Flow verdict checks against.
+  </Card>
+  <Card title="Query your data" icon="magnifying-glass" href="/observability/query">
+    Run TRQL queries against the same telemetry the report reads.
+  </Card>
+</CardGroup>

package/docs/request-feature.mdx

@@ -0,0 +1,6 @@
+---
+title: "Request a feature"
+url: "https://feedback.trigger.dev/"
+---
+
+If you have a feature request or idea for Trigger, we'd love to hear it! You can submit your ideas on our [public roadmap](https://feedback.trigger.dev/). We're always looking for feedback on what to build next, so feel free to submit your ideas or vote on existing ones.

package/docs/roadmap.mdx

@@ -0,0 +1,6 @@
+---
+title: "Roadmap"
+url: "https://feedback.trigger.dev/roadmap"
+---
+
+See what's coming up next on our [public roadmap](https://feedback.trigger.dev/roadmap). We're always looking for feedback on what to build next, so feel free to submit your ideas or vote on existing ones. 

package/docs/run-tests.mdx

@@ -0,0 +1,21 @@
+---
+title: "Run tests"
+description: "You can use the dashboard to run a test of your tasks."
+---
+
+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 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:
+
+- Enter the run's input — a JSON **payload** and optional **metadata**. Scheduled tasks show timestamp fields instead of a payload.
+- Configure run **options** like the machine size, version, queue, tags, retries, max duration, or a delay.
+- Pre-populate the form from a previous run with **Recent runs**, or save and reuse a configuration with **Templates**.
+- Press **Run test** to trigger the run.
+
+![Test page](/images/test-dashboard.png)

package/docs/run-usage.mdx

@@ -0,0 +1,113 @@
+---
+title: "Usage"
+description: "Get compute duration and cost from inside a run, or for a specific block of code."
+---
+
+## Getting the run cost and duration
+
+You can get the cost and duration of the current including retries of the same run.
+
+```ts
+import { task, usage, wait } from "@trigger.dev/sdk";
+
+export const heavyTask = task({
+  id: "heavy-task",
+  machine: {
+    preset: "medium-2x",
+  },
+  run: async (payload, { ctx }) => {
+    // Do some compute
+    const result = await convertVideo(payload.videoUrl);
+
+    // Get the current cost and duration up until this line of code
+    // This includes the compute time of the previous lines
+    let currentUsage = usage.getCurrent();
+    /* currentUsage = {
+        compute: {
+          attempt: {
+            costInCents: 0.01700,
+            durationMs: 1000,
+          },
+          total: {
+            costInCents: 0.0255,
+            durationMs: 1500,
+          },
+        },
+        baseCostInCents: 0.0025,
+        totalCostInCents: 0.028,
+      } 
+      */
+
+    // 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: 10 });
+
+    // This will give the same result as before the wait.
+    currentUsage = usage.getCurrent();
+
+    // Do more compute
+    const result = await convertVideo(payload.videoUrl);
+
+    // This would give a different value
+    currentUsage = usage.getCurrent();
+  },
+});
+```
+
+<Note>
+  In Trigger.dev cloud we do not include time between attempts, before your code executes, or waits
+  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
+
+You can use [runs.retrieve()](/management/runs/retrieve) to get a single run or [runs.list()](/management/runs/list) to get a list of runs. The response will include `costInCents` `baseCostInCents` and `durationMs` fields.
+
+```ts single run
+import { runs } from "@trigger.dev/sdk";
+
+const run = await runs.retrieve("run-id");
+console.log(run.costInCents, run.baseCostInCents, run.durationMs);
+const totalCost = run.costInCents + run.baseCostInCents;
+```
+
+```ts multiple runs
+import { runs } from "@trigger.dev/sdk";
+
+let totalCost = 0;
+for await (const run of runs.list({ tag: "user_123456" })) {
+  totalCost += run.costInCents + run.baseCostInCents;
+  console.log(run.costInCents, run.baseCostInCents, run.durationMs);
+}
+
+console.log("Total cost", totalCost);
+```
+
+## Getting the cost and duration of a block of code
+
+You can also wrap code with `usage.measure` to get the cost and duration of that block of code:
+
+```ts
+import { usage, logger } from "@trigger.dev/sdk";
+
+// Inside a task run function, or inside a function that's called from there.
+const { result, compute } = await usage.measure(async () => {
+  //...Do something for 1 second
+  return {
+    foo: "bar",
+  };
+});
+
+logger.info("Result", { result, compute });
+/* result = {
+    foo: "bar"
+  }
+  compute = {
+    costInCents: 0.01700,
+    durationMs: 1000,
+  }
+*/
+```
+
+This will work from inside the `run` function, our lifecycle hooks (like `onStart`, `onFailure`, `onSuccess`, etc.), or any function you're calling from the `run` function. It won't work for code that's not executed using Trigger.dev.

package/docs/runs/bulk-actions.mdx

@@ -0,0 +1,183 @@
+---
+title: "Bulk actions with the SDK"
+sidebarTitle: "Bulk actions"
+description: "Cancel or replay many runs from the SDK using run IDs or SDK run-list filters."
+---
+
+**Bulk actions let you cancel or replay many runs asynchronously from the SDK by selecting runs with run IDs or SDK run-list filters.**
+
+A bulk action returns a handle immediately. Use the handle to retrieve progress, poll until completion, list previous actions, or abort pending work.
+
+## Create a bulk replay
+
+Use `runs.bulk.replay()` to replay every run that matches a filter.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const action = await runs.bulk.replay({
+  filter: {
+    status: "FAILED",
+    taskIdentifier: "sync-customer",
+    period: "24h",
+  },
+  name: "Replay failed customer syncs",
+  targetRegion: "eu-central-1",
+});
+
+const completed = await runs.bulk.poll(action.id);
+console.log(completed.status, completed.counts);
+```
+
+`filter` accepts the SDK run-list filter fields, excluding pagination fields such as `limit`, `after`, and `before`. This is the TypeScript SDK shape used by `runs.list()` (`from`, `to`, and `period` are top-level fields), not the nested `filter[createdAt]` query shape shown in the raw HTTP list-runs endpoint. Provide at least one filter field; use `runIds` when you want to target specific runs. Relative time filters such as `period` are resolved when the bulk action is created, so later batches process the same fixed time range.
+
+<Warning>
+  Filters inherit the same time semantics as `runs.list()`: when you don't pass `from`, `to`, or `period`, the action defaults to the **last 7 days** and won't target older matching runs. To cover a wider range, pass an explicit `period` (such as `"30d"`), a `from` timestamp, or a `from`/`to` pair. This default only applies to `filter` selections; `runIds` selections are never time-bounded.
+</Warning>
+
+<ParamField body="filter" type="BulkActionFilter">
+  Selects runs using the SDK run-list filter shape, excluding `limit`, `after`, and `before`. In raw HTTP requests these fields are sent as JSON body properties, so time fields are top-level (`from`, `to`, `period`) instead of nested under `createdAt`.
+</ParamField>
+
+<ParamField body="runIds" type="string[]">
+  Selects specific run IDs. Provide either `filter` or `runIds`, not both.
+</ParamField>
+
+<ParamField body="name" type="string" optional>
+  A name for the bulk action.
+</ParamField>
+
+<ParamField body="targetRegion" type="string" optional>
+  Replays matching runs in a specific region. When omitted, each replay keeps the original run's region. This option is only available for `runs.bulk.replay()`.
+</ParamField>
+
+## Create a bulk cancel
+
+Use `runs.bulk.cancel()` to cancel every run that matches a filter, or specific run IDs.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const action = await runs.bulk.cancel({
+  runIds: ["run_1234", "run_5678"],
+  name: "Cancel selected runs",
+});
+
+console.log(action.id);
+```
+
+Only runs that are still cancelable when the action reaches them are canceled. Runs that have already reached a final state count as failures in the bulk action summary.
+
+## Retrieve progress
+
+Use `runs.bulk.retrieve()` to read the current status and aggregate counts.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const action = await runs.bulk.retrieve("bulk_1234");
+
+console.log(action.status);
+console.log(action.counts.total, action.counts.success, action.counts.failure);
+```
+
+The returned bulk action object has these fields:
+
+<ResponseField name="id" type="string">
+  The bulk action ID, starting with `bulk_`.
+</ResponseField>
+
+<ResponseField name="type" type="'CANCEL' | 'REPLAY'">
+  The action being performed.
+</ResponseField>
+
+<ResponseField name="status" type="'PENDING' | 'COMPLETED' | 'ABORTED'">
+  The current bulk action status.
+</ResponseField>
+
+<ResponseField name="counts" type="object">
+  Aggregate processing counts.
+
+  <Expandable title="properties">
+    <ResponseField name="total" type="number">
+      The number of runs selected when the bulk action was created.
+    </ResponseField>
+    <ResponseField name="success" type="number">
+      The number of runs processed successfully.
+    </ResponseField>
+    <ResponseField name="failure" type="number">
+      The number of runs that could not be processed.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="createdAt" type="Date">
+  The date and time the bulk action was created.
+</ResponseField>
+
+<ResponseField name="completedAt" type="Date" optional>
+  The date and time the bulk action completed.
+</ResponseField>
+
+## Poll for completion
+
+Use `runs.bulk.poll()` to wait until the bulk action leaves the `PENDING` state.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const completed = await runs.bulk.poll("bulk_1234", {
+  pollIntervalMs: 2_000,
+});
+
+console.log(completed.status);
+```
+
+## Abort a bulk action
+
+Use `runs.bulk.abort()` to stop future batches from being processed.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+await runs.bulk.abort("bulk_1234");
+```
+
+Abort is best effort. Runs already being processed in the current batch may still finish.
+
+<Note>
+  Each environment can only run a limited number of bulk replays at the same time. If you start a replay while too many are still in progress, the call fails and returns an error. Wait for an in-progress replay to finish or abort one before starting another. Bulk cancels are not subject to this limit.
+</Note>
+
+## List bulk actions
+
+Use `runs.bulk.list()` to page through previous bulk actions in the current environment.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const page = await runs.bulk.list({ limit: 25 });
+
+for (const action of page.data) {
+  console.log(action.id, action.status);
+}
+```
+
+List results support the same auto-pagination helpers as other management API list methods:
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+for await (const action of runs.bulk.list({ limit: 25 })) {
+  console.log(action.id, action.status);
+}
+```
+
+## API reference
+
+The SDK methods use the bulk actions HTTP API:
+
+- [Create bulk action](/management/bulk-actions/create)
+- [List bulk actions](/management/bulk-actions/list)
+- [Retrieve bulk action](/management/bulk-actions/retrieve)
+- [Abort bulk action](/management/bulk-actions/abort)

package/docs/runs/heartbeats.mdx

@@ -0,0 +1,38 @@
+---
+title: "Heartbeats"
+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 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.
+
+```ts
+import { task, heartbeats } from "@trigger.dev/sdk";
+
+export const processLargeDataset = task({
+  id: "process-large-dataset",
+  run: async (payload: { items: string[] }) => {
+    for (const row of payload.items) {
+      await heartbeats.yield();
+      processRow(row);
+    }
+    return { processed: payload.items.length };
+  },
+});
+
+function processRow(row: string) {
+  // synchronous CPU-heavy work
+}
+```
+
+If you see `TASK_RUN_STALLED_EXECUTING`, see [Task run stalled executing](/troubleshooting#task-run-stalled-executing) in the troubleshooting guide.
+
+## 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 [Subscribe to metadata updates](/realtime/backend/subscribe#subscribe-to-metadata-updates-from-your-tasks) for a full example.
+
+## Sending updates to your own system
+
+Trigger.dev doesn’t push run updates to external services. To send progress or heartbeats to your own backend (for example Supabase Realtime), call your API or client from inside the task when you want to emit an update—e.g. in the same loop where you call `heartbeats.yield()` or `metadata.set()`. Use whatever your stack supports: HTTP, the Supabase client, or another SDK.