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

package/docs/runs/priority.mdx

@@ -0,0 +1,8 @@
+---
+title: "Priority"
+description: "Specify a priority when triggering a run."
+---
+
+import Priority from "/snippets/priority.mdx";
+
+<Priority />

package/docs/runs.mdx

@@ -0,0 +1,406 @@
+---
+title: "Runs"
+description: "Understanding the lifecycle of task run execution in Trigger.dev"
+---
+
+import RunBooleanHelpers from "/snippets/run-boolean-helpers.mdx";
+
+In Trigger.dev, the concepts of runs and attempts are fundamental to understanding how tasks are executed and managed. This article explains these concepts in detail and provides insights into the various states a run can go through during its lifecycle.
+
+## What are runs?
+
+A run is created when you trigger a task (e.g. calling `yourTask.trigger({ foo: "bar" })`). It represents a single instance of a task being executed and contains the following key information:
+
+- A unique run ID
+- The current status of the run
+- The payload (input data) for the task
+- Lots of other metadata
+
+## The run lifecycle
+
+A run can go through **various** states during its lifecycle. The following diagram illustrates a typical state transition where a single run is triggered and completes successfully:
+
+![Run Lifecycle](/images/run-lifecycle.png)
+
+Runs can also find themselves in lots of other states depending on what's happening at any given time. The following sections describe all the possible states in more detail.
+
+### Initial states
+
+<Icon icon="rectangle-history" iconType="solid" color="#FBBF24" size={17} /> **Pending version**:
+The task is waiting for a version update because it cannot execute without additional information (task, queue, etc.).
+
+<Icon icon="clock" iconType="solid" color="#878C99" size={17} /> **Delayed**: When a run is triggered
+with a delay, it enters this state until the specified delay period has passed.
+
+<Icon icon="rectangle-history" iconType="solid" color="#878C99" size={17} /> **Queued**: The run is ready
+to be executed and is waiting in the queue.
+
+<Icon icon="rectangle-history" iconType="solid" color="#878C99" size={17} /> **Dequeued**: The task has been dequeued and is being sent to a worker to start executing.
+
+### Execution states
+
+<Icon icon="spinner-third" iconType="duotone" color="#3B82F6" size={17} /> **Executing**: The task is
+currently being executed by a worker.
+
+<Icon icon="hourglass" iconType="solid" color="#878C99" size={17} /> **Waiting**: You have used a
+[triggerAndWait()](/triggering#yourtask-triggerandwait), [batchTriggerAndWait()](/triggering#yourtask-batchtriggerandwait) or a [wait function](/wait). When the wait is complete, the task will resume execution.
+
+### Final states
+
+<Icon icon="circle-check" iconType="solid" color="#28BF5C" size={17} /> **Completed**: The task has successfully
+finished execution.
+
+<Icon icon="ban" iconType="solid" color="#878C99" size={17} /> **Canceled**: The run was manually canceled
+by the user.
+
+<Icon icon="circle-xmark" iconType="solid" color="#E11D48" size={17} /> **Failed**: The task has failed
+to complete successfully due to an error in the task code.
+
+<Icon icon="alarm-exclamation" iconType="solid" color="#E11D48" size={17} /> **Timed out**: Task has
+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, 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.
+
+<Icon icon="trash-can" iconType="solid" color="#878C99" size={17} /> **Expired**: The run's [Time-to-Live](#time-to-live-ttl)
+(TTL) has passed before it could start executing.
+
+## Attempts
+
+An attempt represents a single execution of a task within a run. A run can have one or more attempts, depending on the task's retry settings and whether it fails. Each attempt has:
+
+- A unique attempt ID
+- A status
+- An output (if successful) or an error (if failed)
+
+When a task fails, it will be retried according to its retry settings, creating new attempts until it either succeeds or reaches the retry limit.
+
+![Run with retries](/images/run-with-retries.png)
+
+## Run completion
+
+A run is considered finished when:
+
+1. The last attempt succeeds, or
+2. The task has reached its retry limit and all attempts have failed
+
+At this point, the run will have either an output (if successful) or an error (if failed).
+
+## Boolean helpers
+
+Run objects returned from the API and Realtime include convenient boolean helper methods to check the run's status:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+const run = await runs.retrieve("run_1234");
+
+if (run.isSuccess) {
+  console.log("Run completed successfully");
+}
+```
+
+<RunBooleanHelpers />
+
+These helpers are also available when subscribing to Realtime run updates:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+for await (const run of runs.subscribeToRun("run_1234")) {
+  if (run.isSuccess) {
+    console.log("Run completed successfully!");
+    break;
+  }
+}
+```
+
+## Advanced run features
+
+### Idempotency Keys
+
+When triggering a task, you can provide an idempotency key to ensure the task is executed only once, even if triggered multiple times. This is useful for preventing duplicate executions in distributed systems.
+
+```ts
+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 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.
+
+### Canceling runs
+
+You can cancel an in-progress run using the API or the dashboard:
+
+```ts
+await runs.cancel(runId);
+```
+
+When a run is canceled:
+
+– The task execution is stopped
+
+– The run is marked as canceled
+
+– The task will not be retried
+
+– Any in-progress child runs are also canceled
+
+### Time-to-live (TTL)
+
+TTL is a time-to-live setting that defines the maximum duration a run can remain in a queued state before being automatically expired. You can set a TTL at three levels, with the following precedence:
+
+1. **Per-trigger** (highest priority):
+
+```ts
+await yourTask.trigger({ foo: "bar" }, { ttl: "10m" });
+```
+
+2. **Task-level default**:
+
+```ts
+export const myTask = task({
+  id: "my-task",
+  ttl: "10m",
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+3. **Global config default** (lowest priority):
+
+```ts trigger.config.ts
+export default defineConfig({
+  project: "<project ref>",
+  ttl: "1h",
+});
+```
+
+To opt out of a config-level or task-level TTL for a specific trigger, pass `ttl: 0`:
+
+```ts
+// This run will not have a TTL, even if the task or config defines one
+await yourTask.trigger({ foo: "bar" }, { ttl: 0 });
+```
+
+Similarly, to opt out of a config-level TTL for a specific task, set `ttl: 0` on the task definition:
+
+```ts
+export const longRunningTask = task({
+  id: "long-running-task",
+  ttl: 0, // Opt out of the config-level TTL
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+<Note>
+  Setting `ttl: 0` removes the config-level or task-level TTL, but the platform-level maximum still applies. See [Limits - Maximum run TTL](/limits#maximum-run-ttl) for details.
+</Note>
+
+If the run hasn't started within the specified TTL, it will automatically expire, returning the status `Expired`. This is useful for time-sensitive tasks where immediate execution is important. For example, when you queue many runs simultaneously and exceed your concurrency limits, some runs might be delayed - using TTL ensures they only execute if they can start within your specified timeframe.
+
+Dev runs automatically have a 10-minute TTL. On Trigger.dev Cloud, staging and production runs have a maximum TTL of 14 days applied automatically (runs without an explicit TTL get 14 days; longer TTLs are clamped). See [Limits — Maximum run TTL](/limits#maximum-run-ttl) for details.
+
+![Run with TTL](/images/run-with-ttl.png)
+
+### Delayed runs
+
+You can schedule a run to start after a specified delay:
+
+```ts
+await yourTask.trigger({ foo: "bar" }, { delay: "1h" });
+```
+
+This is useful for tasks that need to be executed at a specific time in the future.
+
+![Run with delay](/images/run-with-delay.png)
+
+### Replaying runs
+
+You can create a new run with the same payload as a previous run:
+
+```ts
+await runs.replay(runId);
+```
+
+This is useful for re-running a task with the same input, especially for debugging or recovering from failures. The new run will use the latest version of the task.
+
+You can also replay runs from the dashboard using the same or different payload. Learn how to do this [here](/replaying).
+
+### Waiting for runs
+
+#### triggerAndWait()
+
+The `triggerAndWait()` function triggers a task and then lets you wait for the result before continuing. [Learn more about triggerAndWait()](/triggering#yourtask-triggerandwait).
+
+![Run with triggerAndWait](</images/run-with-triggerAndWait().png>)
+
+#### batchTriggerAndWait()
+
+Similar to `triggerAndWait()`, the `batchTriggerAndWait()` function lets you batch trigger a task and wait for all the results [Learn more about batchTriggerAndWait()](/triggering#yourtask-batchtriggerandwait).
+
+![Run with batchTriggerAndWait](</images/run-with-batchTriggerAndWait().png>)
+
+### Runs API
+
+#### 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
+import { runs } from "@trigger.dev/sdk";
+
+// Get the first page of runs, returning up to 20 runs
+let page = await runs.list({ limit: 20 });
+
+for (const run of page.data) {
+  console.log(run);
+}
+
+// Keep getting the next page until there are no more runs
+while (page.hasNextPage()) {
+  page = await page.getNextPage();
+  // Do something with the next page of runs
+}
+```
+
+You can also use an Async Iterator to get all runs:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+for await (const run of runs.list({ limit: 20 })) {
+  console.log(run);
+}
+```
+
+You can provide multiple filters to the `list()` function to narrow down the results:
+
+```ts
+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(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
+  batch: "batch_1234", // Filter by batch ID
+  schedule: "sched_1234", // Filter by schedule ID
+});
+```
+
+#### runs.retrieve()
+
+Fetch a single run by it's ID:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+const run = await runs.retrieve(runId);
+```
+
+You can provide the type of the task to correctly type the `run.payload` and `run.output`:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+import type { myTask } from "./trigger/myTask";
+
+const run = await runs.retrieve<typeof myTask>(runId);
+
+console.log(run.payload.foo); // string
+console.log(run.output.bar); // string
+```
+
+If you have just triggered a run, you can pass the entire response object to `retrieve()` and the response will already be typed:
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+import type { myTask } from "./trigger/myTask";
+
+const response = await tasks.trigger<typeof myTask>("my-task", { foo: "bar" });
+const run = await runs.retrieve(response);
+
+console.log(run.payload.foo); // string
+console.log(run.output.bar); // string
+```
+
+#### runs.cancel()
+
+Cancel a run:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+await runs.cancel(runId);
+```
+
+#### runs.replay()
+
+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.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+await runs.reschedule(runId, { delay: "1h" });
+```
+
+### Real-time updates
+
+Subscribe to changes to a specific run in real-time:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+for await (const run of runs.subscribeToRun(runId)) {
+  console.log(run);
+}
+```
+
+Similar to `runs.retrieve()`, you can provide the type of the task to correctly type the `run.payload` and `run.output`:
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+import type { myTask } from "./trigger/myTask";
+
+for await (const run of runs.subscribeToRun<typeof myTask>(runId)) {
+  console.log(run.payload.foo); // string
+  console.log(run.output?.bar); // string | undefined
+}
+```
+
+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 "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.