June 3, 2024

runs.get() & runs.list()

CTO, Trigger.dev

We've added first-class support for getting runs using the SDK in version 3.0.0-beta.36. The list function is especially nice as we're using some pretty neat tricks to make it really easy to paginate through runs.

If you haven't used any of the management functions before, the overview which includes instructions on authentication is a good starting point.

Run this command in your repo to easily upgrade:

npx trigger.dev@beta update

runs.retrieve()

import { runs, APIError } from "@trigger.dev/sdk/v3";
//run IDs start with "run_"
async function getRun(id: string) {
  try {
    const run = await runs.retrieve(id);
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(
        `API error: ${error.status}, ${error.headers}, ${error.body}`
      );
    } else {
      console.error(`Unknown error: ${error.message}`);
    }
  }
}

You get lots of useful information about the run including:

status: (e.g. QUEUED, EXECUTING, COMPLETED, FAILED, etc)
payload: The payload that was sent to the run
output: The output of the run, if it has completed
startedAt: When the run was started
finishedAt: When the run finished, if it has completed
attempts: Information about each attempt, including the status and any error.

Full reference docs.

runs.list()

Auto-pagination

Dealing with list pagination is usually a pain. You get a bunch of items back, then you have to make another request to get the next page, and so on. We've made this super easy with the list function. You can just use a for await loop to iterate through every single matching run.

import { runs } from "@trigger.dev/sdk/v3";
async function fetchAllRuns() {
  const allRuns = [];
  for await (const run of runs.list({ limit: 10 })) {
    allRuns.push(run);
  }
  return allRuns;
}

Be warned: this will go through every single run, so you should break out of the loop when you have what you need. Or at least use a filter to only get the runs you're interested in.

Using getNextPage()

Alternatively, you can get a page then use getNextPage() to get the next page.

import { runs } from "@trigger.dev/sdk/v3";
async function fetchRuns() {
  let page = await runs.list({ limit: 10 });
  for (const run of page.data) {
    console.log(run);
  }
  while (page.hasNextPage()) {
    page = await page.getNextPage();
    // ... do something with the next page
  }
}

Filtering

You can use advanced filtering when listing runs. For example, to get all completed runs in the last year:

for await (const run of runs.list({
  status: ["COMPLETED"],
  period: "1y",
})) {
  console.log(run);
}

Or just encode-video tasks in the past day, that aren't tests and failed:

for await (const run of runs.list({
  taskIdentifier: "encode-video",
  status: ["FAILED", "CRASHED", "INTERRUPTED", "SYSTEM_FAILURE"],
  period: "1d",
  isTest: false,
})) {
  console.log(run);
}