Skip to content

Commit 61fee91

Browse files
ericallamericallam
authored
chore(docs): upgrade for new batch trigger limits and functionality (#2787)
1 parent caa40ce commit 61fee91

File tree

10 files changed

+5342
-16
lines changed

10 files changed

+5342
-16
lines changed

‎docs/batch-queue-stress-test-plan.md‎

Lines changed: 5011 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/docs.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,13 @@
228228
"group": "Tasks API",
229229
"pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
230230
},
231+
{
232+
"group": "Batches API",
233+
"pages": [
234+
"management/batches/create",
235+
"management/batches/stream-items"
236+
]
237+
},
231238
{
232239
"group": "Runs API",
233240
"pages": [
@@ -653,4 +660,4 @@
653660
"destination": "/migrating-from-v3"
654661
}
655662
]
656-
}
663+
}

‎docs/limits.mdx‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -75,20 +75,44 @@ Additional bundles are available for $10/month per 100 concurrent connections. C
7575

7676
## Task payloads and outputs
7777

78-
| Limit | Details |
79-
| :--------------------- | :-------------------------------------------- |
80-
| Single trigger payload | Must not exceed 3MB |
81-
| Batch trigger payload | The total of all payloads must not exceed 5MB |
82-
| Task outputs | Must not exceed 10MB |
78+
| Limit | Details |
79+
| :--------------------- | :----------------------------------------------------------------- |
80+
| Single trigger payload | Must not exceed 3MB |
81+
| Batch trigger payload | Each item can be up to 3MB (SDK 4.3.1+). Prior: 1MB total combined |
82+
| Task outputs | Must not exceed 10MB |
8383

8484
Payloads and outputs that exceed 512KB will be offloaded to object storage and a presigned URL will be provided to download the data when calling `runs.retrieve`. You don't need to do anything to handle this in your tasks however, as we will transparently upload/download these during operation.
8585

8686
## Batch size
8787

88-
A single batch can have a maximum of 500 items.
88+
A single batch can have a maximum of 1,000 items with SDK 4.3.1+. Prior versions are limited to 500 items.
8989

9090
<SoftLimit />
9191

92+
## Batch trigger rate limits
93+
94+
Batch triggering uses a token bucket algorithm to rate limit the number of runs you can trigger per environment. Each run in a batch consumes one token.
95+
96+
| Pricing tier | Bucket size | Refill rate |
97+
| :----------- | :---------- | :-------------------- |
98+
| Free | 1,200 runs | 100 runs every 10 sec |
99+
| Hobby | 5,000 runs | 500 runs every 5 sec |
100+
| Pro | 5,000 runs | 500 runs every 5 sec |
101+
102+
**How it works**: You can burst up to your bucket size, then tokens refill at the specified rate. For example, a Free user can trigger 1,200 runs immediately, then must wait for tokens to refill (100 runs become available every 10 seconds).
103+
104+
## Batch processing concurrency
105+
106+
The number of batches that can be processed concurrently per environment.
107+
108+
| Pricing tier | Limit |
109+
| :----------- | :-------------------- |
110+
| Free | 1 concurrent batch |
111+
| Hobby | 10 concurrent batches |
112+
| Pro | 10 concurrent batches |
113+
114+
This limits how many batches can have their items actively being processed into runs at the same time.
115+
92116
## Log retention
93117

94118
| Pricing tier | Limit |

‎docs/management/batches/create.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Create batch"
3+
openapi: "openapi POST /api/v3/batches"
4+
---
5+

‎docs/management/batches/stream-items.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Stream batch items"
3+
openapi: "openapi POST /api/v3/batches/{batchId}/items"
4+
---
5+

‎docs/openapi.yml‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,159 @@ paths:
4343
schema:
4444
$ref: "#/components/schemas/Error"
4545

46+
/api/v3/batches:
47+
post:
48+
operationId: createBatch
49+
externalDocs:
50+
description: Find more info here
51+
url: "https://trigger.dev/docs/triggering"
52+
tags:
53+
- Batches
54+
summary: Create a batch (Phase 1)
55+
description: |
56+
Phase 1 of 2-phase batch API. Creates a batch record and optionally blocks the parent run for batchTriggerAndWait.
57+
After creating a batch, stream items via POST /api/v3/batches/{batchId}/items.
58+
requestBody:
59+
required: true
60+
content:
61+
application/json:
62+
schema:
63+
$ref: "#/components/schemas/CreateBatchRequest"
64+
responses:
65+
"202":
66+
description: Batch successfully created
67+
content:
68+
application/json:
69+
schema:
70+
$ref: "#/components/schemas/CreateBatchResponse"
71+
headers:
72+
x-trigger-jwt-claims:
73+
description: JWT claims for the batch
74+
schema:
75+
type: string
76+
x-trigger-jwt:
77+
description: JWT token for browser clients
78+
schema:
79+
type: string
80+
"400":
81+
description: Invalid request (e.g., runCount <= 0 or exceeds maximum)
82+
content:
83+
application/json:
84+
schema:
85+
$ref: "#/components/schemas/Error"
86+
"401":
87+
description: Unauthorized - API key is missing or invalid
88+
"422":
89+
description: Validation error
90+
content:
91+
application/json:
92+
schema:
93+
$ref: "#/components/schemas/Error"
94+
"429":
95+
description: Rate limit exceeded
96+
headers:
97+
X-RateLimit-Limit:
98+
description: Maximum number of requests allowed
99+
schema:
100+
type: integer
101+
X-RateLimit-Remaining:
102+
description: Number of requests remaining
103+
schema:
104+
type: integer
105+
X-RateLimit-Reset:
106+
description: Unix timestamp when the rate limit resets
107+
schema:
108+
type: integer
109+
Retry-After:
110+
description: Seconds to wait before retrying
111+
schema:
112+
type: integer
113+
content:
114+
application/json:
115+
schema:
116+
$ref: "#/components/schemas/Error"
117+
"500":
118+
description: Internal server error
119+
content:
120+
application/json:
121+
schema:
122+
$ref: "#/components/schemas/Error"
123+
124+
/api/v3/batches/{batchId}/items:
125+
post:
126+
operationId: streamBatchItems
127+
externalDocs:
128+
description: Find more info here
129+
url: "https://trigger.dev/docs/triggering"
130+
tags:
131+
- Batches
132+
summary: Stream batch items (Phase 2)
133+
description: |
134+
Phase 2 of 2-phase batch API. Accepts an NDJSON stream of batch items and enqueues them.
135+
Each line in the body should be a valid BatchItemNDJSON object.
136+
The stream is processed with backpressure - items are enqueued as they arrive.
137+
The batch is sealed when the stream completes successfully.
138+
parameters:
139+
- name: batchId
140+
in: path
141+
required: true
142+
description: The batch ID returned from POST /api/v3/batches
143+
schema:
144+
type: string
145+
requestBody:
146+
required: true
147+
content:
148+
application/x-ndjson:
149+
schema:
150+
type: string
151+
description: |
152+
NDJSON (newline-delimited JSON) stream where each line is a BatchItemNDJSON object.
153+
Example:
154+
{"index":0,"task":"my-task","payload":{"key":"value1"}}
155+
{"index":1,"task":"my-task","payload":{"key":"value2"}}
156+
application/ndjson:
157+
schema:
158+
type: string
159+
description: |
160+
NDJSON (newline-delimited JSON) stream where each line is a BatchItemNDJSON object.
161+
responses:
162+
"200":
163+
description: Items successfully processed
164+
content:
165+
application/json:
166+
schema:
167+
$ref: "#/components/schemas/StreamBatchItemsResponse"
168+
"400":
169+
description: Invalid request (e.g., invalid JSON, item exceeds maximum size)
170+
content:
171+
application/json:
172+
schema:
173+
$ref: "#/components/schemas/Error"
174+
"401":
175+
description: Unauthorized - API key is missing or invalid
176+
content:
177+
application/json:
178+
schema:
179+
$ref: "#/components/schemas/Error"
180+
"415":
181+
description: Unsupported Media Type - Content-Type must be application/x-ndjson or application/ndjson
182+
content:
183+
application/json:
184+
schema:
185+
$ref: "#/components/schemas/Error"
186+
"422":
187+
description: Validation error
188+
content:
189+
application/json:
190+
schema:
191+
$ref: "#/components/schemas/Error"
192+
"500":
193+
description: Internal server error
194+
content:
195+
application/json:
196+
schema:
197+
$ref: "#/components/schemas/Error"
198+
46199
components:
47200
schemas:
48201
Error:
@@ -130,6 +283,91 @@ components:
130283
type: object
131284
additionalProperties: true
132285
description: A JSON object that represents the deserialized payload or context.
286+
CreateBatchRequest:
287+
type: object
288+
required:
289+
- runCount
290+
properties:
291+
runCount:
292+
type: integer
293+
minimum: 1
294+
description: Expected number of items in the batch. Must be a positive integer.
295+
parentRunId:
296+
type: string
297+
description: Parent run ID (friendly ID) for batchTriggerAndWait.
298+
resumeParentOnCompletion:
299+
type: boolean
300+
description: Whether to resume parent on completion. Set to true for batchTriggerAndWait.
301+
idempotencyKey:
302+
type: string
303+
description: Idempotency key for the batch. If provided and a batch with this key already exists, the existing batch will be returned.
304+
CreateBatchResponse:
305+
type: object
306+
required:
307+
- id
308+
- runCount
309+
- isCached
310+
properties:
311+
id:
312+
type: string
313+
description: The batch ID (friendly ID). Use this to stream items via POST /api/v3/batches/{batchId}/items.
314+
runCount:
315+
type: integer
316+
description: The expected run count.
317+
isCached:
318+
type: boolean
319+
description: Whether this response came from a cached/idempotent batch.
320+
idempotencyKey:
321+
type: string
322+
description: The idempotency key if provided.
323+
BatchItemNDJSON:
324+
type: object
325+
required:
326+
- index
327+
- task
328+
properties:
329+
index:
330+
type: integer
331+
minimum: 0
332+
description: Zero-based index of this item. Used for idempotency and ordering.
333+
task:
334+
type: string
335+
description: The task identifier to trigger.
336+
payload:
337+
description: The payload for this task run. Can be any JSON value.
338+
options:
339+
type: object
340+
additionalProperties: true
341+
description: Options for this specific item.
342+
StreamBatchItemsResponse:
343+
type: object
344+
required:
345+
- id
346+
- itemsAccepted
347+
- itemsDeduplicated
348+
- sealed
349+
properties:
350+
id:
351+
type: string
352+
description: The batch ID.
353+
itemsAccepted:
354+
type: integer
355+
description: Number of items successfully accepted.
356+
itemsDeduplicated:
357+
type: integer
358+
description: Number of items that were deduplicated (already enqueued).
359+
sealed:
360+
type: boolean
361+
description: |
362+
Whether the batch was sealed and is ready for processing.
363+
If false, the batch needs more items before processing can start.
364+
Clients should check this field and retry with missing items if needed.
365+
enqueuedCount:
366+
type: integer
367+
description: Total items currently enqueued. Only present when sealed=false to help with retries.
368+
expectedCount:
369+
type: integer
370+
description: Expected total item count. Only present when sealed=false to help with retries.
133371
securitySchemes:
134372
BearerAuth:
135373
type: http

‎docs/self-hosting/env/webapp.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,9 @@ mode: "wide"
101101
| `TASK_PAYLOAD_MAXIMUM_SIZE` | No | 3145728 (3MB) | Max task payload size. |
102102
| `BATCH_TASK_PAYLOAD_MAXIMUM_SIZE` | No | 1000000 (1MB) | Max batch payload size. |
103103
| `TASK_RUN_METADATA_MAXIMUM_SIZE` | No | 262144 (256KB) | Max metadata size. |
104-
| `MAX_BATCH_V2_TRIGGER_ITEMS` | No | 500 | Max batch size. |
104+
| `MAX_BATCH_V2_TRIGGER_ITEMS` | No | 500 | Max batch size (legacy v2 API). |
105+
| `STREAMING_BATCH_MAX_ITEMS` | No | 1000 | Max items in streaming batch (v3 API, requires SDK 4.3.1+). |
106+
| `STREAMING_BATCH_ITEM_MAXIMUM_SIZE` | No | 3145728 (3MB) | Max size per item in streaming batch. |
105107
| `MAXIMUM_DEV_QUEUE_SIZE` | No | — | Max dev queue size. |
106108
| `MAXIMUM_DEPLOYED_QUEUE_SIZE` | No | — | Max deployed queue size. |
107109
| **OTel limits** | | | |

‎docs/snippets/rate-limit-hit-use-batchtrigger.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
The most common cause of hitting the API rate limit is if you’re calling `trigger()` on a task in a loop, instead of doing this use `batchTrigger()` which will trigger multiple tasks in a single API call. You can have up to 500 tasks in a single batch trigger call.
1+
The most common cause of hitting the API rate limit is if you're calling `trigger()` on a task in a loop, instead of doing this use `batchTrigger()` which will trigger multiple tasks in a single API call. You can have up to 1,000 tasks in a single batch trigger call with SDK 4.3.1+ (500 in prior versions).

0 commit comments

Comments
 (0)