Create batch

POST

api

batches

Create a batch (Phase 1)

curl --request POST \
  --url https://api.trigger.dev/api/v3/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "runCount": 2,
  "taskIdentifiers": [
    "<string>"
  ],
  "parentRunId": "<string>",
  "resumeParentOnCompletion": true,
  "idempotencyKey": "<string>"
}
'

import requests

url = "https://api.trigger.dev/api/v3/batches"

payload = {
    "runCount": 2,
    "taskIdentifiers": ["<string>"],
    "parentRunId": "<string>",
    "resumeParentOnCompletion": True,
    "idempotencyKey": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    runCount: 2,
    taskIdentifiers: ['<string>'],
    parentRunId: '<string>',
    resumeParentOnCompletion: true,
    idempotencyKey: '<string>'
  })
};

fetch('https://api.trigger.dev/api/v3/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trigger.dev/api/v3/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'runCount' => 2,
    'taskIdentifiers' => [
        '<string>'
    ],
    'parentRunId' => '<string>',
    'resumeParentOnCompletion' => true,
    'idempotencyKey' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trigger.dev/api/v3/batches"

	payload := strings.NewReader("{\n  \"runCount\": 2,\n  \"taskIdentifiers\": [\n    \"<string>\"\n  ],\n  \"parentRunId\": \"<string>\",\n  \"resumeParentOnCompletion\": true,\n  \"idempotencyKey\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trigger.dev/api/v3/batches")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"runCount\": 2,\n  \"taskIdentifiers\": [\n    \"<string>\"\n  ],\n  \"parentRunId\": \"<string>\",\n  \"resumeParentOnCompletion\": true,\n  \"idempotencyKey\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trigger.dev/api/v3/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"runCount\": 2,\n  \"taskIdentifiers\": [\n    \"<string>\"\n  ],\n  \"parentRunId\": \"<string>\",\n  \"resumeParentOnCompletion\": true,\n  \"idempotencyKey\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "runCount": 123,
  "isCached": true,
  "idempotencyKey": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

runCount

integer

required

Expected number of items in the batch. Must be a positive integer, up to the server's maximum batch size (1,000 by default; self-hosted instances can configure it). Requests above the maximum return a 400.

Required range: x >= 1

taskIdentifiers

string[]

Distinct task identifiers of the items in the batch. Used to authorize tokens scoped to specific tasks. If omitted, only credentials with broad task access are accepted.

Minimum array length: 1

parentRunId

string

Parent run ID (friendly ID) for batchTriggerAndWait.

resumeParentOnCompletion

boolean

Whether to resume parent on completion. Set to true for batchTriggerAndWait.

idempotencyKey

string

Idempotency key for the batch. If provided and a batch with this key already exists, the existing batch will be returned.

Response

Batch successfully created

string

required

The batch ID (friendly ID). Use this to stream items via POST /api/v3/batches/{batchId}/items.

runCount

integer

required

The expected run count.

isCached

boolean

required

Whether this response came from a cached/idempotent batch.

idempotencyKey

string

The idempotency key if provided.

⌘I

Create a batch (Phase 1)

curl --request POST \
  --url https://api.trigger.dev/api/v3/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "runCount": 2,
  "taskIdentifiers": [
    "<string>"
  ],
  "parentRunId": "<string>",
  "resumeParentOnCompletion": true,
  "idempotencyKey": "<string>"
}
'

import requests

url = "https://api.trigger.dev/api/v3/batches"

payload = {
    "runCount": 2,
    "taskIdentifiers": ["<string>"],
    "parentRunId": "<string>",
    "resumeParentOnCompletion": True,
    "idempotencyKey": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    runCount: 2,
    taskIdentifiers: ['<string>'],
    parentRunId: '<string>',
    resumeParentOnCompletion: true,
    idempotencyKey: '<string>'
  })
};

fetch('https://api.trigger.dev/api/v3/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trigger.dev/api/v3/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'runCount' => 2,
    'taskIdentifiers' => [
        '<string>'
    ],
    'parentRunId' => '<string>',
    'resumeParentOnCompletion' => true,
    'idempotencyKey' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trigger.dev/api/v3/batches"

	payload := strings.NewReader("{\n  \"runCount\": 2,\n  \"taskIdentifiers\": [\n    \"<string>\"\n  ],\n  \"parentRunId\": \"<string>\",\n  \"resumeParentOnCompletion\": true,\n  \"idempotencyKey\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trigger.dev/api/v3/batches")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"runCount\": 2,\n  \"taskIdentifiers\": [\n    \"<string>\"\n  ],\n  \"parentRunId\": \"<string>\",\n  \"resumeParentOnCompletion\": true,\n  \"idempotencyKey\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trigger.dev/api/v3/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"runCount\": 2,\n  \"taskIdentifiers\": [\n    \"<string>\"\n  ],\n  \"parentRunId\": \"<string>\",\n  \"resumeParentOnCompletion\": true,\n  \"idempotencyKey\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "runCount": 123,
  "isCached": true,
  "idempotencyKey": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

API reference

Tasks API

Batches API

Runs API

Bulk actions API

Errors API

Webhooks API

Queues API

Concurrency limits API

Schedules API

Env Vars API

Deployments API

Waitpoints API

Sessions API

Query API

Authorizations

Body

Response