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.

​
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.

Was this page helpful?

subscribeToRunsubscribeToBatch