Management API

The Management API lets you manage runs, deployments, environment variables, queues, and more — from any backend or script.

Installation

The Management API is part of @trigger.dev/sdk:

npm i @trigger.dev/sdk@latest

Authentication

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

// Explicit configuration
configure({
  secretKey: process.env["TRIGGER_SECRET_KEY"],
});

// Or set TRIGGER_SECRET_KEY env var — configure() call is optional

Runs

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

// List runs
const response = await runs.list({
  status: ["COMPLETED", "FAILED"],
  taskIdentifier: ["my-task"],
  from: new Date("2024-04-01"),
  to: new Date(),
  tag: ["user_123"],
});

// Async iterator (auto-paginates)
for await (const run of runs.list({ limit: 20 })) {
  console.log(run.id, run.status);
}

// Retrieve a typed run
import type { myTask } from "./trigger/myTask";
const run = await runs.retrieve<typeof myTask>(runId);
console.log(run.payload.foo); // fully typed
console.log(run.output.bar);

// Cancel a run (also cancels in-progress child runs)
await runs.cancel(runId);

// Replay with same payload, latest code
await runs.replay(runId);

// Reschedule a delayed run
await runs.reschedule(runId, { delay: "2h" });

// Update run metadata
await runs.update(runId, { metadata: { status: "reviewed" } });

// Real-time subscription
for await (const run of runs.subscribeToRun<typeof myTask>(runId)) {
  if (run.isCompleted) break;
  console.log(run.status);
}

Deployments

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

// Get latest deployment
const latest = await deployments.retrieveLatest("my-task");

// Retrieve by ID
const deploy = await deployments.retrieve(deploymentId);

// Promote to current version
await deployments.promote(deploymentId);

Environment Variables

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

// List all env vars
const vars = await envvars.list("my-project", "prod");

// Retrieve one
const secret = await envvars.retrieve("my-project", "prod", "API_KEY");

// Create
await envvars.create("my-project", "prod", {
  name: "NEW_VAR",
  value: "secret-value",
});

// Update
await envvars.update("my-project", "prod", "EXISTING_VAR", {
  value: "new-value",
});

// Delete
await envvars.delete("my-project", "prod", "OLD_VAR");

// Import multiple at once
await envvars.import("my-project", "prod", {
  variables: [
    { name: "VAR_1", value: "val1" },
    { name: "VAR_2", value: "val2" },
  ],
  override: true, // overwrite existing
});

Queues

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

// List queues
const queueList = await queues.list();

// Retrieve queue
const queue = await queues.retrieve("my-queue");

// Pause queue (new runs won't execute)
await queues.pause("my-queue");

// Resume queue
await queues.resume("my-queue");

// Override concurrency limit
await queues.setConcurrencyLimit("my-queue", 5);

// Reset to default concurrency
await queues.resetConcurrencyLimit("my-queue");

Batches

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

// Create a batch
const batch = await batches.create([
  { id: "my-task", payload: { item: 1 } },
  { id: "my-task", payload: { item: 2 } },
]);

// Stream batch items as they complete
for await (const item of batches.streamItems(batchId)) {
  console.log(item.output);
}

Pagination

The SDK supports automatic pagination via async iterators:

// Auto-paginate with for-await
for await (const run of runs.list({ status: ["COMPLETED"] })) {
  console.log(run.id);
}

// Manual pagination
let page = await runs.list({ limit: 10 });
while (page.hasNextPage()) {
  page = await page.getNextPage();
  for (const run of page.data) {
    console.log(run.id);
  }
}

Error Handling

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

try {
  await runs.retrieve("invalid-id");
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status, error.message);
  }
}