DEV Community

Cover image for How to use Trigger.dev API ?
Wanda
Wanda

Posted on • Originally published at apidog.com

How to use Trigger.dev API ?

TL;DR / Quick Answer

The Trigger.dev API allows you to trigger, monitor, replay, and cancel background job runs, removing the need to build your own queuing and orchestration system. When paired with Apidog, you can document workflows, test payloads, inspect job states, and build repeatable internal references for backend and QA teams.

Try Apidog today

Introduction

Background jobs start simple, but quickly become complex in production: from queuing tasks and handling retries, to adding observability and support for delayed execution, you can end up maintaining a job system instead of focusing on your core features.

Trigger.dev is an open-source background jobs framework for authoring long-running workflows in async code, supporting retries, scheduling, observability, and real-time run updates. According to the official docs (reviewed March 26, 2026), Trigger.dev provides a task-centric SDK, a Runs API, batching, delayed execution, replay, cancellation, and real-time subscriptions for run state changes.

đź’ˇ Tip: Apidog is a powerful tool to complement your Trigger.dev workflow. Use it to document payloads, save environment configs, test endpoints for task triggering and status updates, model webhook flows, and publish internal documentation your team can rely on.

What the Trigger.dev API Solves

Trigger.dev is built for teams needing reliable background execution without building a queue, worker fleet, retry logic, and monitoring from scratch. Define your tasks in code, and Trigger.dev manages execution, retries, waiting states, delayed runs, and observability.

Trigger.dev workflow illustration

Key features from the docs:

  • Write tasks in your codebase
  • Trigger tasks programmatically with typed payloads
  • Monitor each run and attempt
  • Replay or cancel runs as needed
  • Subscribe to real-time run updates
  • Deploy on Trigger.dev Cloud or self-host

In real-world scenarios, background work often needs:

  • Reliable retries
  • Status visibility for long-running jobs
  • Idempotency to avoid duplicate tasks
  • Delays/TTLs for time-sensitive work
  • Documented and testable operational workflows

Common architecture:

User action -> Trigger task -> Queue/execution -> Run status changes -> Result handling -> Retry/replay
Enter fullscreen mode Exit fullscreen mode

When each piece is siloed, debugging and collaboration slow down. Apidog bridges this gap by providing a single place to document inputs, run states, and API calls for your Trigger.dev workflows.

How the Trigger.dev API Works

Trigger.dev centers on tasks and runs.

Tasks

A task is a unit of background work you define in your app. Write the logic in your code, and Trigger.dev handles orchestration, retries, and execution.

Unlike simple job APIs, Trigger.dev is a framework + platform: you define tasks, then use the SDK/API to trigger and monitor them reliably.

Runs

A run is created each time you trigger a task. It represents a single execution instance with a specific payload, and includes:

  • Unique run ID
  • Current status
  • Input payload
  • Metadata

Most operational workflows revolve around runs, not generic HTTP requests.

Attempts

Each run may have multiple attempts (retries). If the task fails, Trigger.dev creates additional attempts until success or hitting the retry limit.

Note: "Run failed" ≠ "Attempt failed". A run is the overall lifecycle; an attempt is each execution inside that lifecycle.

Lifecycle States

Trigger.dev defines multiple run states: queued, executing, waiting, completed, canceled, and failed. Waiting states are distinct from active execution—important for managing concurrency and load.

Common states to document:

  • QUEUED — Task accepted, not yet running
  • EXECUTING — Actively processing
  • WAITING — Paused, not executing
  • Completed/terminal states — Success, canceled, or failed

Documenting these state transitions in Apidog helps support and QA teams understand job progress.

Send and Monitor Your First Trigger.dev Run

Start with the SDK, as recommended in the docs.

Trigger a Task 

import { tasks } from "@trigger.dev/sdk";
import type { myTask } from "./trigger/myTask";

const response = await tasks.trigger<typeof myTask>({
  foo: "bar"
});

console.log(response.id);
Enter fullscreen mode Exit fullscreen mode

This creates a run and returns a response you can use to fetch the run later.

Retrieve a Run 

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

const run = await runs.retrieve("run_1234");

console.log(run.status);
console.log(run.payload);
console.log(run.output);
Enter fullscreen mode Exit fullscreen mode

To maintain strong typing for payloads and outputs:

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

const run = await runs.retrieve<typeof myTask>("run_1234");

console.log(run.payload.foo);
console.log(run.output?.bar);
Enter fullscreen mode Exit fullscreen mode

Subscribe to Real-Time Updates

Monitor jobs in real-time without polling:

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

for await (const run of runs.subscribeToRun("run_1234")) {
  console.log(run.status);

  if (run.isCompleted) {
    console.log("Run completed");
    break;
  }
}
Enter fullscreen mode Exit fullscreen mode

Ideal for progress UIs and internal monitoring tools.

Cancel or Replay a Run 

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

await runs.cancel("run_1234");
await runs.replay("run_1234");
Enter fullscreen mode Exit fullscreen mode

Gives teams control to stop or restart background jobs when necessary.

Use Idempotency and TTL

Prevent duplicates and control job timing:

await yourTask.trigger(
  { orderId: "ord_123" },
  {
    idempotencyKey: "order-ord_123",
    ttl: "10m"
  }
);
Enter fullscreen mode Exit fullscreen mode
  • Idempotency: Prevents duplicate execution for the same event
  • TTL: Ensures time-sensitive tasks don't start too late

Document these operational contracts in Apidog to keep your team aligned on payloads and guarantees.

Best Practices for Trigger.dev API Workflows

After initial integration, focus on these:

1. Treat Idempotency as Part of the API Contract

Define your idempotency strategy early—don't leave it as a patch.

2. Separate Trigger Success from Business Success

A triggered run means the job started, not that it finished successfully. Reflect this in docs, UI, and alerts.

3. Document the Meaning of Each Run State

Explain run states in your docs. Backend engineers may know what WAITING means, but others might not.

4. Decide When Replay Is Safe

Not all tasks are safe to replay (e.g., financial operations, external writes). Define clear rules.

5. Define Cancellation Behavior

When canceling a run, clarify what users see, what happens to related tasks, and next steps for support.

6. Keep Apidog and Trigger.dev Docs in Sync

Update Apidog docs and examples whenever your payloads or operational notes change to avoid drift.

Download Apidog free to document Trigger.dev workflows, save request samples, and ensure your team has a shared operational reference.

Trigger.dev Alternatives and Comparisons

If you're evaluating Trigger.dev, compare it against other common solutions:

Option Strength Tradeoff
Hand-rolled queues and workers Maximum control Higher maintenance and observability cost
Traditional queue infrastructure Familiar worker pattern More setup and more custom orchestration work
Trigger.dev Strong developer experience for long-running background jobs You adopt Trigger.dev's task and run model
Trigger.dev + Apidog Strong execution framework plus better shared API workflow docs Two tools instead of one

Focus on which setup lets your team implement and operate reliable background jobs fastest. Trigger.dev handles execution; Apidog provides the documentation, testing, and clarity around those workflows.

Conclusion

Trigger.dev is a robust option for teams needing reliable background job execution without building an entire platform. The key is not just async execution, but a structured model for triggering, observing, replaying, delaying, and canceling workflows.

To move quickly: define a real business workflow in Trigger.dev, then document trigger inputs, run states, and recovery steps in Apidog. This gives your team a clear, actionable path from code to operations.

FAQ

What is the Trigger.dev API used for?

The Trigger.dev API is for triggering and managing background job execution via tasks and runs. It supports run retrieval, listing, replay, cancellation, delays, TTLs, batching, and real-time updates.

Is Trigger.dev a REST API or an SDK?

Most developers use the SDK and broader Trigger.dev platform. The docs focus on tasks, runs, and runtime helpers rather than a REST-only interface.

What is a run in Trigger.dev?

A run is a single execution instance of a task, including payload, status, metadata, and one or more attempts (for retries).

What is the difference between a run and an attempt?

A run is the full lifecycle object for a triggered task. An attempt is each execution inside that run—multiple attempts may occur if retries are needed.

Can I replay or cancel Trigger.dev runs?

Yes. Use runs.replay() and runs.cancel() to manage run execution after triggering a task.

How do I monitor Trigger.dev runs in real-time?

Trigger.dev provides real-time subscriptions to monitor run updates as they happen. Useful for dashboards and user-facing progress UIs.

Where does Apidog fit if I use Trigger.dev?

Apidog helps you document inputs, outputs, status transitions, and supporting endpoints for your Trigger.dev workflows, making it easy to share reliable API references across engineering and QA teams.

Top comments (0)