Overview & Authentication

Using the Trigger.dev v3 management API

Installation

The management API is available through the same @trigger.dev/sdk package used in defining and triggering tasks. If you have already installed the package in your project, you can skip this step.

npm

npm i @trigger.dev/sdk@latest

Usage

All v3 functionality is provided through the @trigger.dev/sdk/v3 module. You can import the entire module or individual resources as needed.

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

configure({
  // this is the default and if the `TRIGGER_SECRET_KEY` environment variable is set, can omit calling configure
  secretKey: process.env["TRIGGER_SECRET_KEY"],
});

async function main() {
  const runs = await runs.list({
    limit: 10,
    status: ["COMPLETED"],
  });
}

main().catch(console.error);

Authentication

There are two methods of authenticating with the management API: using a secret key associated with a specific environment in a project (secretKey), or using a personal access token (personalAccessToken). Both methods should only be used in a backend server, as they provide full access to the project.

Support for client-side authentication is coming soon to v3 but is not available at the time of writing.

Certain API functions work with both authentication methods, but require different arguments depending on the method used. For example, the runs.list function can be called using either a secretKey or a personalAccessToken, but the projectRef argument is required when using a personalAccessToken:

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

// Using secretKey authentication
configure({
  secretKey: process.env["TRIGGER_SECRET_KEY"], // starts with tr_dev_ or tr_prod_
});

function secretKeyExample() {
  return runs.list({
    limit: 10,
    status: ["COMPLETED"],
  });
}

// Using personalAccessToken authentication
configure({
  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
});

function personalAccessTokenExample() {
  // Notice the projectRef argument is required when using a personalAccessToken
  return runs.list("prof_1234", {
    limit: 10,
    status: ["COMPLETED"],
    projectRef: "tr_proj_1234567890",
  });
}

View endpoint support

Consult the following table to see which endpoints support each authentication method.

Endpoint	Secret key	Personal Access Token
task.trigger	✅
task.batchTrigger	✅
runs.list	✅	✅
runs.retrieve	✅
runs.cancel	✅
runs.replay	✅
envvars.list	✅	✅
envvars.retrieve	✅	✅
envvars.upload	✅	✅
envvars.create	✅	✅
envvars.update	✅	✅
envvars.del	✅	✅
schedules.list	✅
schedules.create	✅
schedules.retrieve	✅
schedules.update	✅
schedules.activate	✅
schedules.deactivate	✅
schedules.del	✅

Secret key

Secret key authentication scopes the API access to a specific environment in a project, and works with certain endpoints. You can read our API Keys guide for more information.

Personal Access Token (PAT)

A PAT is a token associated with a specific user, and gives access to all the orgs, projects, and environments that the user has access to. You can identify a PAT by the tr_pat_ prefix. Because a PAT does not scope access to a specific environment, you must provide the projectRef argument when using a PAT (and sometimes the environment as well).

For example, when uploading environment variables using a PAT, you must provide the projectRef and environment arguments:

import { configure, envvars } from "@trigger.dev/sdk/v3";

configure({
  secretKey: process.env["TRIGGER_ACCESS_TOKEN"], // starts with tr_pat_
});

await envvars.upload("proj_1234", "dev", {
  variables: {
    MY_ENV_VAR: "MY_ENV_VAR_VALUE",
  },
  override: true,
});

Handling errors

When the SDK method is unable to connect to the API server, or the API server returns a non-successful response, the SDK will throw an ApiError that you can catch and handle:

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

async function main() {
  try {
    const run = await runs.retrieve("run_1234");
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`API error: ${error.status}, ${error.headers}, ${error.body}`);
    } else {
      console.error(`Unknown error: ${error.message}`);
    }
  }
}

Retries

The SDK will automatically retry requests that fail due to network errors or server errors. By default, the SDK will retry requests up to 3 times, with an exponential backoff delay between retries.

You can customize the retry behavior by passing a requestOptions option to the configure function:

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

configure({
  requestOptions: {
    retry: {
      maxAttempts: 5,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 5000,
      factor: 1.8,
      randomize: true,
    },
  },
});

All SDK functions also take a requestOptions parameter as the last argument, which can be used to customize the request options. You can use this to disable retries for a specific request:

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

async function main() {
  const run = await runs.retrieve("run_1234", {
    retry: {
      maxAttempts: 1, // Disable retries
    },
  });
}

When running inside a task, the SDK ignores customized retry options for certain functions (e.g., task.trigger, task.batchTrigger), and uses retry settings optimized for task execution.

Auto-pagination

All list endpoints in the management API support auto-pagination. You can use for await … of syntax to iterate through items across all pages:

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;
}

You can also use helpers on the return value from any list method to get the next/previous page of results:

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

async function main() {
  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
  }
}

Advanced usage

Accessing raw HTTP responses

All API methods return a Promise subclass ApiPromise that includes helpers for accessing the underlying HTTP response:

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

async function main() {
  const { data: run, response: raw } = await runs.retrieve("run_1234").withResponse();

  console.log(raw.status);
  console.log(raw.headers);

  const response = await runs.retrieve("run_1234").asResponse(); // Returns a Response object

  console.log(response.status);
  console.log(response.headers);
}