---
title: "Trigger a task"
method: POST
path: "/api/v1/tasks/{taskIdentifier}/trigger"
tags: ["tasks"]
---

# Trigger a task

`POST /api/v1/tasks/{taskIdentifier}/trigger`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/tasks/{taskIdentifier}/trigger`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/tasks/:taskIdentifier/trigger/post.ts> (a function with typed inputs; its response is checked against the schema)

Trigger a task by its identifier.

## Request body

- TriggerTaskRequestBody
  - `payload` unknown
  - `context` unknown
  - `options` object
    - `queue` QueueOptions
      - `name` string: You can define a shared queue and then pass the name in to your task.
      - `concurrencyLimit` integer: An optional property that specifies the maximum number of concurrent run executions. If this property is omitted, the task can potentially use up the full concurrency of an environment.
    - `concurrencyKey` string: Scope the concurrency limit to a specific key.
    - `idempotencyKey` string: An optional property that specifies the idempotency key used to prevent creating duplicate runs. If you provide an existing idempotency key, we will return the existing run ID.
    - `ttl` union: The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1).
      - string
      - number
    - `delay` string: The delay before the task is executed. This can be a Date object, a string like `1h` or a date-time string. * "1h" - 1 hour * "30d" - 30 days * "15m" - 15 minutes * "2w" - 2 weeks * "60s" - 60 seconds * new Date("2025-01-01T00:00:00Z")
    - `tags` union: One or more tags to attach to a run. Runs can have a maximum of 10 tags.
      - string: A single run tag. Must be less than 128 characters.
      - RunTag[]
    - `machine` 'micro' | 'small-1x' | 'small-2x' | 'medium-1x' | 'medium-2x' | 'large-1x' | 'large-2x': The machine preset to use for this run. This will override the task's machine preset and any defaults.

## Response `200`

Task triggered successfully

- TriggerTaskResponse
  - `id` string: The ID of the run that was triggered.

## Other responses

- `400`: Invalid request parameters or body
- `401`: Unauthorized request
- `404`: Resource not found

## Changes

- **2026-02-24** `6ec7a0ed3a5e`: 2 breaking
  - added `#/components/schemas/RunTags` to the `options/tags` request property `allOf` list
  - the `options/tags` request property type changed from `array, string` to no type
- **2025-01-15** `b53962c2295b`: 1 info
  - added the new optional request property `options/machine`
- **2024-07-24** `059ad75e9ad0`: 1 info
  - added the new optional request property `options/tags`
- **2024-07-10** `25b8615054f7`: 2 breaking, 1 info
  - removed `#/components/schemas/TTLString, #/components/schemas/TTLNumber` from the `options/ttl` request property `oneOf` list
  - the `options/ttl` request property type changed from no type to `string, number`
  - added the new optional request property `options/delay`
- **2024-07-10** `ce0c456e6565`: 1 info
  - added the new optional request property `options/ttl`

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/tasks/:taskIdentifier/trigger/post.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)