From e6e8aeb993df7693857ea50fde0f1ad24f932497 Mon Sep 17 00:00:00 2001 From: Wes Mason Date: Fri, 10 Jul 2026 11:31:42 +0100 Subject: [PATCH] docs(limits): document automatic payload offloading for triggers and batches (#4217) ## Summary The limits page didn't spell out that large payloads offload to object storage automatically, and its single "512KB" note conflated two different thresholds. This clarifies the behaviour. On the way in, the SDK uploads any trigger or batch-item payload over 128KB to object storage before sending, so large triggers and batches don't hit the request body limit (`trigger` / `triggerAndWait` since 4.5.0, `batchTrigger` / `batchTriggerAndWait` since 4.5.2). On retrieval, payloads and outputs over 512KB are stored in object storage and returned as a presigned URL from `runs.retrieve`. --- docs/limits.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/limits.mdx b/docs/limits.mdx index d68760da1..a27901a09 100644 --- a/docs/limits.mdx +++ b/docs/limits.mdx @@ -104,7 +104,11 @@ Additional bundles are available for $10/month per 100 concurrent connections. C | Batch trigger payload | Each item can be up to 3MB (SDK 4.3.1+). Prior: 1MB total combined | | Task outputs | Must not exceed 10MB | -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. +Large payloads and outputs are offloaded to object storage automatically. You don't need to do anything to handle this in your tasks, as we upload and download the data transparently during operation. + +On the way in, the SDK uploads any trigger or batch-item payload over 128KB to object storage before sending, so large triggers and batches don't exceed the request body limit. `trigger` and `triggerAndWait` have done this since SDK 4.5.0, and `batchTrigger` and `batchTriggerAndWait` (including the by-id and by-task variants) do too from SDK 4.5.2. + +Payloads and outputs over 512KB are kept in object storage rather than inline. Calling `runs.retrieve` returns that offloaded data as a presigned download URL (`payloadPresignedUrl` / `outputPresignedUrl`). ## Batch size