Trigger a Task

Overview

Trigger a task by its identifier. The task must be deployed and active in the target environment. Returns the ID of the newly created run.

Authentication with a secret key is required. This endpoint is not available with a Personal Access Token.

Endpoint

POST https://api.trigger.dev/api/v1/tasks/{taskIdentifier}/trigger

Path parameters

string

required

The id you assigned to the task in your task() definition, e.g. "my-task".

Request body

any

Any JSON-serializable value to pass as the task’s payload. The shape must match what the task’s run function expects.

object

An optional JSON object that is available inside the run via context. Useful for passing request-scoped metadata.

object

Show options properties

object

Override the queue this run is placed on.

Show queue properties

string

Name of the queue. Runs with the same queue name share a concurrency limit.

integer

Maximum number of concurrent runs allowed on this queue (0–1000).

string

Scope the concurrency limit to a specific key. For example, pass a user ID to limit how many runs a single user can have executing at once.

string

Prevents duplicate runs. If a run with this key already exists (and was created recently), the existing run ID is returned instead of creating a new run.

string | number

Time-to-live for this run. If the run has not started executing within this time it will be removed from the queue and never execute. Accepts a duration string like "1h", "30m", "90s" or a number of seconds (minimum 1).

string

Delay before the run is enqueued. Accepts a duration string ("1h", "30d", "15m") or an ISO 8601 date-time string. The run will not start before this time.

string[]

Up to 10 tags to attach to the run. Tags can be used to filter runs in the dashboard or via runs.list. Each tag must be 1–128 characters. We recommend namespacing: user_1234567 or org:9876543.

string

Override the machine preset for this run. One of: micro, small-1x, small-2x, medium-1x, medium-2x, large-1x, large-2x.

Response

string

The unique ID of the newly created run, prefixed with run_.

Examples

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

// Trigger using the task's exported handle (type-safe payload)
import { myTask } from "./trigger/my-task";

const handle = await myTask.trigger(
  { message: "Hello, world!" },
  {
    idempotencyKey: "unique-key-123",
    concurrencyKey: "user123",
    queue: { name: "my-task-queue", concurrencyLimit: 5 },
    tags: ["user:123", "org:456"],
  }
);

console.log(handle.id); // run_1234

curl -X POST "https://api.trigger.dev/api/v1/tasks/my-task/trigger" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_dev_1234" \
  -d '{
    "payload": { "message": "Hello, world!" },
    "context": { "user": "user123" },
    "options": {
      "queue": { "name": "default", "concurrencyLimit": 5 },
      "concurrencyKey": "user123",
      "idempotencyKey": "unique-key-123"
    }
  }'

Response example

{
  "id": "run_p4omhh45hgxxnq1re6ovy"
}

Overview

Tasks & Runs

Schedules & Queues

Waitpoints & Env Vars

Overview

Endpoint

Path parameters

Request body

Response

Examples

Response example

​Overview

​Endpoint

​Path parameters

​Request body

​Response

​Examples

​Response example

Overview

Endpoint

Path parameters

Request body

Response

Examples

Response example