Skip to main content

​
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

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

​
Request body

​
payload
any
Any JSON-serializable value to pass as the task’s payload. The shape must match what the task’s run function expects.
​
context
object
An optional JSON object that is available inside the run via context. Useful for passing request-scoped metadata.
​
options
object

​
Response

​
id
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

​
Response example

{
  "id": "run_p4omhh45hgxxnq1re6ovy"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us