---
title: "Create bulk action"
method: POST
path: "/api/v1/bulk-actions"
tags: ["bulk-actions"]
---

# Create bulk action

`POST /api/v1/bulk-actions`

## Request

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

Create an asynchronous bulk action to cancel or replay runs selected by run IDs or filters.

## Request body

- union
  - object
    - `action` 'cancel', required
    - `filter` BulkActionFilter, required: Selects runs using SDK-style run-list filter fields, excluding pagination fields. In HTTP requests these fields are sent as JSON body properties, so time fields are top-level (`from`, `to`, `period`) instead of nested under `createdAt`. Provide at least one property.
      - `status` union
        - 'PENDING_VERSION' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE'
        - string[]
      - `taskIdentifier` union: The identifier of the task that was run.
        - string
        - string[]
      - `version` union: The worker version that executed the run.
        - string
        - string[]
      - `from` union: Start of the time range as an ISO date string or Unix timestamp in milliseconds.
        - string, date-time
        - number
      - `to` union: End of the time range as an ISO date string or Unix timestamp in milliseconds.
        - string, date-time
        - number
      - `period` string: Relative time period to select, such as `24h` or `30d`.
      - `bulkAction` string: Select runs that were processed by another bulk action.
      - `tag` union: Select runs with one or more tags.
        - string
        - string[]
      - `schedule` string: Select runs created by a schedule.
      - `isTest` boolean: Select test or non-test runs.
      - `batch` string: Select runs in a batch.
      - `queue` union
        - QueueTypeName
          - `type` 'task' | 'custom', required
          - `name` string, required
        - QueueTypeName[]
          - `type` 'task' | 'custom', required
          - `name` string, required
      - `machine` union: Select runs by machine preset.
        - string
        - string[]
      - `region` union: Select runs by region.
        - string
        - string[]
    - `name` string
  - object
    - `action` 'cancel', required
    - `runIds` string[], required
    - `name` string
  - object
    - `action` 'replay', required
    - `filter` BulkActionFilter, required: Selects runs using SDK-style run-list filter fields, excluding pagination fields. In HTTP requests these fields are sent as JSON body properties, so time fields are top-level (`from`, `to`, `period`) instead of nested under `createdAt`. Provide at least one property.
      - `status` union
        - 'PENDING_VERSION' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE'
        - string[]
      - `taskIdentifier` union: The identifier of the task that was run.
        - string
        - string[]
      - `version` union: The worker version that executed the run.
        - string
        - string[]
      - `from` union: Start of the time range as an ISO date string or Unix timestamp in milliseconds.
        - string, date-time
        - number
      - `to` union: End of the time range as an ISO date string or Unix timestamp in milliseconds.
        - string, date-time
        - number
      - `period` string: Relative time period to select, such as `24h` or `30d`.
      - `bulkAction` string: Select runs that were processed by another bulk action.
      - `tag` union: Select runs with one or more tags.
        - string
        - string[]
      - `schedule` string: Select runs created by a schedule.
      - `isTest` boolean: Select test or non-test runs.
      - `batch` string: Select runs in a batch.
      - `queue` union
        - QueueTypeName
          - `type` 'task' | 'custom', required
          - `name` string, required
        - QueueTypeName[]
          - `type` 'task' | 'custom', required
          - `name` string, required
      - `machine` union: Select runs by machine preset.
        - string
        - string[]
      - `region` union: Select runs by region.
        - string
        - string[]
    - `name` string
    - `targetRegion` string: Region identifier to replay runs in. When omitted, each replay keeps the original run's region.
  - object
    - `action` 'replay', required
    - `runIds` string[], required
    - `name` string
    - `targetRegion` string: Region identifier to replay runs in. When omitted, each replay keeps the original run's region.

## Response `202`

Bulk action accepted

- CreateBulkActionResponse
  - `id` string, required

## Other responses

- `400`: Invalid request parameters or body
- `401`: Unauthorized request
- `422`: Unprocessable entity
- `429`: Too many concurrent bulk replays

## Changes

- **2026-07-13** `2f617c841946`: 1 breaking, 1 info
  - removed `subschema #1, subschema #2` from the request body `oneOf` list
  - added `subschema #1: Cancel by filter, subschema #2: Cancel by run IDs, subschema #3: Replay by filter, subschema #4: Replay by run IDs` to the request body `oneOf` list
- **2026-07-10** `840003aec346`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/bulk-actions/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)