How to use Trigger.dev API ?

TL;DR / Quick Answer

The Trigger.dev API helps you trigger, monitor, replay, and cancel background job runs without building your own queueing and orchestration layer from scratch. If you pair Trigger.dev with Apidog, you can document your run workflows, test payloads, inspect run states, and share a repeatable internal reference for your backend and QA teams.

Try Apidog today

Introduction

Background jobs look simple until they start failing in production. You queue a task, wait for the result, add retries, add observability, add delayed execution, and suddenly you are maintaining an entire job system instead of shipping the feature you cared about.

Trigger.dev is an open-source background jobs framework for writing long-running workflows in plain async code, with retries, scheduling, observability, and realtime run updates built in. Based on the official Trigger.dev docs reviewed on March 26, 2026, the platform provides a task-centric SDK, a Runs API, batching support, delayed execution, replay, cancelation, and realtime subscriptions for run state changes.

Apidog fits into this workflow as the shared API workspace around your Trigger.dev implementation. You can use it to document Trigger.dev payloads, save environment values, test supporting endpoints around task triggering and status checks, model webhook or callback flows, and publish internal docs your backend and QA teams can follow.

What the Trigger.dev API Solves

Trigger.dev is built for teams that need reliable background execution without stitching together a queue, worker fleet, retry system, and monitoring layer by hand.

Instead of managing those pieces separately, you define tasks in code and let Trigger.dev handle execution, retries, waiting states, delayed runs, and observability.

From the official docs, the core workflow is:

• Write tasks in your existing codebase
• Trigger them programmatically with typed payloads
• Monitor each run and attempt over time
• Replay or cancel runs when needed
• Subscribe to realtime run updates
• Run on Trigger.dev Cloud or self-host

That matters because background work is rarely just "run this function later." In production, teams usually need:

• Reliable retries for transient failures
• Status visibility during long-running work
• Idempotency to avoid duplicate execution
• Delays and TTLs for time-sensitive jobs
• A safe way to document and test operational workflows

A typical architecture looks like this:

User action
  -> Trigger task
  -> Queue and execution
  -> Run status changes
  -> Result handling
  -> Retry or replay

If every step lives in a different place, debugging slows down. One person checks logs, another checks the dashboard, another replays jobs manually, and nobody shares the same request examples or status vocabulary.

Apidog helps close that gap by giving your team one place to document:

• Trigger inputs
• Expected payload formats
• Run states
• Recovery actions
• Supporting API calls around your Trigger.dev workflows

How the Trigger.dev API Works

Trigger.dev is centered on three concepts:

• Tasks
• Runs
• Attempts

Tasks

A task is the unit of background work you define in your application. You write the logic in code, then Trigger.dev handles execution, retries, and orchestration around it.

This is different from a traditional "remote job API" where you post arbitrary jobs to a black box. Trigger.dev is a framework plus platform. Your application defines tasks, and Trigger.dev gives you an API and SDK to trigger and monitor them reliably.

Runs

According to the official docs, a run is created whenever you trigger a task.

A run represents one instance of a task executing with a specific payload. Each run has:

• A unique run ID
• A current status
• The input payload
• Associated metadata

Most operational workflows in Trigger.dev revolve around runs rather than generic HTTP requests.

Attempts

A run can contain one or more attempts.

If the task succeeds on the first try, the run has a single attempt. If it fails and retries, Trigger.dev creates additional attempts until the task succeeds or reaches the retry limit.

That means:

Run failed != Attempt failed

The run is the full lifecycle object. The attempt is one execution inside that lifecycle.

This distinction is important when you build dashboards, alerts, support tooling, or QA test plans.

Lifecycle States

Trigger.dev documents several run-state helpers, including queued, executing, waiting, completed, canceled, and failed states. It also distinguishes waiting states from active execution states, which matters when you reason about concurrency and system load.

For internal docs, define each state in practical terms:

State type	Operational meaning
Queued or delayed	Work has been accepted but is not running yet
Executing or dequeued	Work is actively consuming execution time
Waiting	The run is paused without actively executing
Completed or terminal	The run finished with success or another terminal outcome

This lifecycle vocabulary is worth documenting in Apidog, especially if support, QA, or product teams need to reason about job progress.

Send and Monitor Your First Trigger.dev Run

The official docs show Trigger.dev usage through the SDK. That is the right starting point because it reflects how most teams integrate the platform.

Trigger a Task

Here is a simplified example based on the docs:

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

This creates a run and returns an ID you can use to fetch the full run later.

In Apidog, document the payload shape as an example request body:

{
  "foo": "bar"
}

Also document the response field your application depends on:

{
  "id": "run_1234"
}

Retrieve a Run

Once the task is triggered, retrieve the 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);

If you have the task type available, keep payload and output typing accurate:

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

For internal documentation, capture example run states and expected outputs so other developers know what to check during debugging.

Subscribe to Realtime Updates

One of Trigger.dev's more useful capabilities is realtime run monitoring. Instead of polling blindly, subscribe to run changes:

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

This is a good fit for:

• User-facing progress UIs
• Internal operational dashboards
• QA test tooling
• Long-running import or export workflows

Cancel or Replay a Run

Trigger.dev also documents ways to cancel and replay runs:

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

await runs.cancel("run_1234");
await runs.replay("run_1234");

This matters operationally because background workflows do not always end with the first successful implementation. Teams need a safe way to stop a run, rerun a task, or recover after a transient issue.

Document these actions carefully:

Action	Document before enabling
Cancel	What the user sees, what state is final, and whether side effects may already exist
Replay	Whether the task is safe to rerun and how duplicate side effects are prevented

Use Idempotency and TTL

The docs also call out idempotency keys and TTL settings. These are important if your tasks can be triggered by user actions, webhook retries, or distributed services.

Example:

await yourTask.trigger(
  { orderId: "ord_123" },
  {
    idempotencyKey: "order-ord_123",
    ttl: "10m",
  }
);

This gives you two protections:

• You avoid duplicate execution for the same business event.
• You stop time-sensitive work from starting too late.

Document the idempotency strategy alongside the payload. For example:

{
  "payload": {
    "orderId": "ord_123"
  },
  "idempotencyKey": "order-ord_123",
  "ttl": "10m"
}

This turns execution behavior into an API contract your team can review and test.

Best Practices for Trigger.dev API Workflows

Once the basic integration works, focus on the operational details.

1. Treat Idempotency as Part of the API Contract

If the same event can arrive twice, define the idempotency key strategy early.

Do not leave it as a late-stage reliability fix.

Example convention:

order-{orderId}
user-import-{importId}
invoice-sync-{invoiceId}

Document the convention in Apidog with examples for each workflow.

2. Separate Trigger Success from Business Success

A successful trigger only means the run was created. It does not mean the underlying job finished successfully.

Make that distinction clear in:

• API docs
• UI copy
• Alerts
• QA test cases
• Support runbooks

A practical status model might look like:

Trigger accepted -> Run created
Run completed -> Business process finished
Run failed -> Business process did not finish

3. Document the Meaning of Each Run State

Your backend team may understand WAITING or delayed states immediately. Other teams may not.

For each state, document:

• What it means
• Whether user action is needed
• Whether support should intervene
• Whether the run can be replayed
• Whether cancelation is safe

4. Decide When Replay Is Safe

Replay is useful, but not every task is safe to rerun.

Be careful with tasks that perform:

• Financial side effects
• Outbound emails or messages
• Third-party writes
• Inventory updates
• User-visible state changes

Before enabling replay as an operational action, define how duplicate effects are prevented.

5. Define Cancelation Behavior Clearly

Cancelation is not only an SDK action. It is a product and operations decision.

Document:

• What the user sees after cancelation
• Whether partial work may already exist
• Whether child work continues
• What support should do next
• Whether a canceled run can be replayed

6. Keep Apidog and Trigger.dev Docs Aligned

If your internal payload schema changes, update the saved Apidog examples and operational notes at the same time.

At minimum, keep these synchronized:

• Trigger payload examples
• Expected run output examples
• Run-state descriptions
• Idempotency key rules
• TTL rules
• Replay and cancelation guidance

Otherwise, your docs will drift from your execution model quickly.

Trigger.dev Alternatives and Comparisons

If you are evaluating Trigger.dev, you are probably also comparing queue-first systems, internal cron and worker setups, or broader workflow platforms.

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

The useful comparison is not "which tool sends HTTP requests."

The better question is:

Which setup gives your team the fastest path from background job idea to reliable production workflow?

Trigger.dev helps with execution. Apidog helps with the documentation, testing, and team clarity around that execution.

Implementation Checklist

Use this checklist when adding a new Trigger.dev workflow.

[ ] Define the task in code
[ ] Define the payload schema
[ ] Add sample payloads in Apidog
[ ] Trigger the task from the application
[ ] Store or expose the run ID where needed
[ ] Retrieve run status for debugging or UI display
[ ] Subscribe to realtime updates if users need progress
[ ] Define idempotency key rules
[ ] Define TTL rules for time-sensitive work
[ ] Document run states
[ ] Document replay safety
[ ] Document cancelation behavior
[ ] Add QA examples for success, failure, retry, replay, and cancelation

Conclusion

Trigger.dev is a strong fit for teams that want reliable background execution without building a full jobs platform from scratch.

The key idea is not just that you can run tasks asynchronously. Trigger.dev gives you a structured model for triggering, observing, replaying, delaying, and canceling long-running work.

A practical way to start:

1. Pick one real business workflow.
2. Define it as a Trigger.dev task.
3. Trigger it from your application.
4. Retrieve and monitor the run.
5. Add idempotency and TTL rules.
6. Document the payload, run states, and recovery actions in Apidog.

That gives your team a cleaner path from implementation to operations than relying on dashboard knowledge alone.

FAQ

What is the Trigger.dev API used for?

The Trigger.dev API is used to trigger and manage background job execution through tasks and runs. Based on the official docs, it supports run retrieval, listing, replay, cancelation, delays, TTLs, batching, and realtime run subscriptions.

Is Trigger.dev a REST API or an SDK?

For most developers, it is experienced through the SDK and the broader Trigger.dev platform. The docs emphasize tasks, runs, and runtime helpers rather than a simple standalone REST-only interface.

What is a run in Trigger.dev?

A run is one execution instance of a task. It includes the payload, status, metadata, and one or more attempts depending on whether retries occur.

What is the difference between a run and an attempt?

A run is the full lifecycle object for a triggered task. An attempt is one execution inside that run. If retries happen, one run can contain multiple attempts.

Can I replay or cancel Trigger.dev runs?

Yes. The official docs describe both runs.replay() and runs.cancel() for managing run execution after a task has been triggered.

How do I monitor Trigger.dev runs in realtime?

Trigger.dev documents realtime subscriptions that let you watch run updates as they happen. This is useful for operational dashboards and user-facing progress experiences.

Where does Apidog fit if I use Trigger.dev?

Apidog fits around the workflow. It helps you document the inputs, outputs, status transitions, and supporting endpoints your application uses alongside Trigger.dev, then share that reference across engineering and QA teams.