runs.subscribeToRunsWithTag

Subscribes to all changes to runs with a specific tag.

Example

import { runs } from "@trigger.dev/sdk/v3";

for await (const run of runs.subscribeToRunsWithTag("user:1234")) {
  console.log(run);
}

This function subscribes to all changes to runs with a specific tag. It returns an async iterator that yields the run object whenever a run with the specified tag is updated. This iterator will never complete, so you must manually break out of the loop when you no longer want to receive updates.

Authentication

This function supports both server-side and client-side authentication. For server-side authentication, use your API key. For client-side authentication, you must generate a public access token with one of the following scopes:

• read:runs
• read:tags:<tagName>

To generate a public access token, use the auth.createPublicToken function:

import { auth } from "@trigger.dev/sdk/v3";

// Somewhere in your backend code
const publicToken = await auth.createPublicToken({
  scopes: {
    read: {
      tags: ["user:1234"],
    },
  },
});

Response

The AsyncIterator yields an object with the following 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.

number · number · required

Sequential number assigned to the run.

status · RunStatus · required

Current status of the run.

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

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.

ttl · string

Time-to-live duration for the run.

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.