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

# runs.subscribeToBatch

> Subscribes to all changes for runs in a batch.

<RequestExample>
  ```ts Example theme={null}
  import { runs } from "@trigger.dev/sdk/v3";

  for await (const run of runs.subscribeToBatch("batch_1234")) {
    console.log(run);
  }
  ```
</RequestExample>

This function subscribes to all changes for runs in a batch. It returns an async iterator that yields the a run object whenever a run in the batch is updated. The iterator does not complete on it's own, you must manually `break` the loop when you want to stop listening for 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:batch:<batchId>`
* `read:runs` will provide access to all runs (not recommended for production use)

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

```ts theme={null}
import { auth } from "@trigger.dev/sdk/v3";

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

### Response

The AsyncIterator yields an object with the following properties:

<ParamField path="id" type="string" required>
  The run ID.
</ParamField>

<ParamField path="taskIdentifier" type="string" required>
  The task identifier.
</ParamField>

<ParamField path="payload" type="object" required>
  The input payload for the run.
</ParamField>

<ParamField path="output" type="object">
  The output result of the run.
</ParamField>

<ParamField path="createdAt" type="Date" required>
  Timestamp when the run was created.
</ParamField>

<ParamField path="updatedAt" type="Date" required>
  Timestamp when the run was last updated.
</ParamField>

<ParamField path="number" type="number" required>
  Sequential number assigned to the run.
</ParamField>

<ParamField path="status" type="RunStatus" required>
  Current status of the run.

  <Accordion title="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                                                     |
  </Accordion>
</ParamField>

<ParamField path="durationMs" type="number" required>
  Duration of the run in milliseconds.
</ParamField>

<ParamField path="costInCents" type="number" required>
  Total cost of the run in cents.
</ParamField>

<ParamField path="baseCostInCents" type="number" required>
  Base cost of the run in cents before any additional charges.
</ParamField>

<ParamField path="tags" type="string[]" required>
  Array of tags associated with the run.
</ParamField>

<ParamField path="idempotencyKey" type="string">
  Key used to ensure idempotent execution.
</ParamField>

<ParamField path="expiredAt" type="Date">
  Timestamp when the run expired.
</ParamField>

<ParamField path="ttl" type="string">
  Time-to-live duration for the run.
</ParamField>

<ParamField path="finishedAt" type="Date">
  Timestamp when the run finished.
</ParamField>

<ParamField path="startedAt" type="Date">
  Timestamp when the run started.
</ParamField>

<ParamField path="delayedUntil" type="Date">
  Timestamp until which the run is delayed.
</ParamField>

<ParamField path="queuedAt" type="Date">
  Timestamp when the run was queued.
</ParamField>

<ParamField path="metadata" type="Record<string, DeserializedJson>">
  Additional metadata associated with the run.
</ParamField>

<ParamField path="error" type="SerializedError">
  Error information if the run failed.
</ParamField>

<ParamField path="isTest" type="boolean" required>
  Indicates whether this is a test run.
</ParamField>