> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# The run object

> The run object schema for Realtime subscriptions

The [run object](https://trigger.dev/docs/realtime/run-object.md#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](#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.

> [accordion] 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.

```ts theme={"theme":"css-variables"}
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.

```ts theme={"theme":"css-variables"}
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>()`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.