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

# Trigger a task

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

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

---

[API](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api.md) · [All operations](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/winsenlabs/trigger-dev-v3-rest-api/revisions/737c498e605b/schema)