From f7d859ad07725f1e8f9addaf6c691a24db30fc0c Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 25 Sep 2026 16:26:59 +0000
Subject: [PATCH 1/2] docs: document segment_index beyond 999 and APPEND pacing
for 16 GB uploads
---
x-api/media/quickstart/media-upload-chunked.mdx | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/x-api/media/quickstart/media-upload-chunked.mdx b/x-api/media/quickstart/media-upload-chunked.mdx
index 9d4d53dde..6bc66c06e 100644
--- a/x-api/media/quickstart/media-upload-chunked.mdx
+++ b/x-api/media/quickstart/media-upload-chunked.mdx
@@ -89,7 +89,11 @@ Use `tweet_video` for a regular Post. Use `amplify_video` for Ads creatives. See
## Step 2: Upload chunks (APPEND)
-Upload each chunk to `POST /2/media/upload/{id}/append`. Keep each segment at or below **5 MB** (the server maximum is 8 MB). Segments are indexed from `0`.
+Upload each chunk to `POST /2/media/upload/{id}/append`. Keep each segment at or below **5 MB** (the server maximum is 8 MB). Segments are indexed from `0` and increase by one for each chunk.
+
+
+Large Premium uploads need more than 1,000 segments. A 16 GB video takes about 2,000 APPEND requests at 8 MB per segment, or about 3,300 at 5 MB. `segment_index` is not capped at `999`, so keep incrementing it until the whole file is uploaded.
+
@@ -155,6 +159,15 @@ for (let offset = 0; offset < fileBuffer.length; offset += chunkSize) {
- Failed chunks can be retried individually
+### Pace APPEND requests for large files
+
+APPEND requests count against the [`POST /2/media/upload/:id/append` rate limit](/x-api/fundamentals/rate-limits) of 1,875 requests per 15 minutes per user. A multi-GB upload can reach this limit before it finishes.
+
+- Read the `x-rate-limit-remaining` and `x-rate-limit-reset` headers on each APPEND response.
+- If you receive a `429`, wait until the `x-rate-limit-reset` time, then retry the same `segment_index`.
+- Don't restart from segment `0`. Resume from the first segment that didn't succeed, then call FINALIZE after the last segment.
+- Use larger segments (up to 8 MB) to reduce the number of APPEND requests.
+
---
## Step 3: Finalize upload (FINALIZE)
From ad8c6009c168897eda77d46ab2b82e9662cdd8ee Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sat, 26 Sep 2026 01:13:50 +0000
Subject: [PATCH 2/2] docs: state 0-9999 segment_index range, self-serve APPEND
limits, and 24h session validity
---
x-api/media/quickstart/media-upload-chunked.mdx | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/x-api/media/quickstart/media-upload-chunked.mdx b/x-api/media/quickstart/media-upload-chunked.mdx
index 6bc66c06e..646dbcd95 100644
--- a/x-api/media/quickstart/media-upload-chunked.mdx
+++ b/x-api/media/quickstart/media-upload-chunked.mdx
@@ -92,7 +92,7 @@ Use `tweet_video` for a regular Post. Use `amplify_video` for Ads creatives. See
Upload each chunk to `POST /2/media/upload/{id}/append`. Keep each segment at or below **5 MB** (the server maximum is 8 MB). Segments are indexed from `0` and increase by one for each chunk.
-Large Premium uploads need more than 1,000 segments. A 16 GB video takes about 2,000 APPEND requests at 8 MB per segment, or about 3,300 at 5 MB. `segment_index` is not capped at `999`, so keep incrementing it until the whole file is uploaded.
+An upload session accepts up to 10,000 segments, so valid `segment_index` values are `0` through `9999`. This applies to every media category and account tier. A 16 GB video takes about 2,048 APPEND requests at 8 MB per segment, or about 3,277 at 5 MB.
@@ -161,12 +161,14 @@ for (let offset = 0; offset < fileBuffer.length; offset += chunkSize) {
### Pace APPEND requests for large files
-APPEND requests count against the [`POST /2/media/upload/:id/append` rate limit](/x-api/fundamentals/rate-limits) of 1,875 requests per 15 minutes per user. A multi-GB upload can reach this limit before it finishes.
+APPEND requests count against the [`POST /2/media/upload/:id/append` rate limit](/x-api/fundamentals/rate-limits). For self-serve tiers (Basic, Pro, and pay-per-use), the limit is 1,875 requests per 15 minutes per user. Enterprise packages have higher limits. Treat the `x-rate-limit-limit` header as the authoritative limit for your plan. A multi-GB upload can reach this limit before it finishes.
-- Read the `x-rate-limit-remaining` and `x-rate-limit-reset` headers on each APPEND response.
+An upload session stays valid for 24 hours, and each APPEND response returns the session's `expires_at`. Pausing until `x-rate-limit-reset` doesn't expire the upload.
+
+- Read the `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset` headers on each APPEND response.
- If you receive a `429`, wait until the `x-rate-limit-reset` time, then retry the same `segment_index`.
- Don't restart from segment `0`. Resume from the first segment that didn't succeed, then call FINALIZE after the last segment.
-- Use larger segments (up to 8 MB) to reduce the number of APPEND requests.
+- Use larger segments (up to 8 MB) to reduce the number of APPEND requests. At 8 MB, a 16 GB upload spans roughly two 15-minute windows at the 1,875-request limit.
---