The run object

The run object schema for Realtime subscriptions

The run object is the main object returned by Realtime subscriptions (e.g., runs.subscribeToRun()). It contains all the information about the run, including the run ID, task identifier, payload, output, and more.

Type-safety is supported for the run object, so you can infer the types of the run’s payload and output. See type-safety for more information.

The run object

Properties

id · string · required

The run ID.

taskIdentifier · string · required

The task identifier.

payload · object · required

The input payload for the run.

output · object

The output result of the run.

createdAt · Date · required

Timestamp when the run was created.

updatedAt · Date · required

Timestamp when the run was last updated.

status · RunStatus · required

Current status of the run.

RunStatus enum

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

durationMs · number · required

Duration of the run in milliseconds.

costInCents · number · required

Total cost of the run in cents.

baseCostInCents · number · required

Base cost of the run in cents before any additional charges.

tags · string[] · required

Array of tags associated with the run.

idempotencyKey · string

Key used to ensure idempotent execution.

expiredAt · Date

Timestamp when the run expired.

finishedAt · Date

Timestamp when the run finished.

startedAt · Date

Timestamp when the run started.

delayedUntil · Date

Timestamp until which the run is delayed.

queuedAt · Date

Timestamp when the run was queued.

metadata · Record<string, DeserializedJson>

Additional metadata associated with the run.

error · SerializedError

Error information if the run failed.

isTest · boolean · required

Indicates whether this is a test run.

realtimeStreams · string[] · required

Names of the Realtime streams on the run.

isQueued · boolean · required

true if the run is queued, delayed or waiting for a version update.

isExecuting · boolean · required

true if the run is dequeued or executing.

isWaiting · boolean · required

true if the run is waiting.

isCompleted · boolean · required

true if the run has finished, either successfully or with any failure status.

isFailed · boolean · required

true if the run failed, crashed, hit a system failure, expired or timed out.

isSuccess · boolean · required

true if the run completed successfully.

isCancelled · boolean · required

true if the run was canceled.

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.

import { runs, tasks } from "@trigger.dev/sdk";
import type { myTask } from "./trigger/my-task";

// Somewhere in your backend code
async function myBackend() {
  const handle = await tasks.trigger("my-task", { some: "data" });

  for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
    // This will log the run every time it changes
    console.log(run.payload.some);

    if (run.output) {
      // This will log the output if it exists
      console.log(run.output.some);
    }
  }
}

When using subscribeToRunsWithTag, you can pass a union of task types for all the possible tasks that can have the tag.

import { runs } from "@trigger.dev/sdk";
import type { myTask, myOtherTask } from "./trigger/my-task";

// Somewhere in your backend code
for await (const run of runs.subscribeToRunsWithTag<typeof myTask | typeof myOtherTask>("my-tag")) {
  // You can narrow down the type based on the taskIdentifier
  switch (run.taskIdentifier) {
    case "my-task": {
      console.log("Run output:", run.output.foo); // This will be type-safe
      break;
    }
    case "my-other-task": {
      console.log("Run output:", run.output.bar); // This will be type-safe
      break;
    }
  }
}

This works with all realtime subscription functions:

• runs.subscribeToRun<TaskType>()
• runs.subscribeToRunsWithTag<TaskType>()
• runs.subscribeToBatch<TaskType>()