Threads

Threads Carousel API

How to publish a multi-image carousel post to Threads via API.

By André LugAugust 25, 2026

Quick answer

To publish a Threads carousel, send 2 to 20 media URLs in the media array of the same POST /api/posts request used for single posts — PostGate builds Meta's is_carousel_item containers and the CAROUSEL parent automatically. Photos and videos can mix in one carousel, and the whole thing counts as one post against the 250-per-day quota.

Threads does support multi-image carousels — unlike some newer Meta surfaces, this isn't limited to a single photo or video per post. A Threads carousel takes 2 to 20 items, can mix photos and videos in the same post, and — importantly — counts as one post against Meta's daily publishing quota, not one per item.

What is a Threads carousel under the hood?

On Meta's Graph API, a carousel is built from individual media containers marked is_carousel_item, then wrapped in a parent container with media_type: CAROUSEL that references all the child IDs. PostGate does this automatically the moment you send more than one item in the media array — you don't construct containers yourself.

How do you publish a carousel?

Send two or more media URLs (or pre-uploaded media IDs) in the media array on the same POST /api/posts request used for a single-item post. The caption in post.body is attached to the carousel as a whole, not to individual items.

Publish a 3-image carouselPostGate API

curl -X POST "https://postgate.studio/api/posts" \
  -H "Authorization: Bearer $POSTGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: threads-carousel-001" \
  -d '{
    "post": { "body": "Three shots from the launch event." },
    "profiles": ["pro_threads_8f21"],
    "media": [
      "https://cdn.example.com/event-1.jpg",
      "https://cdn.example.com/event-2.jpg",
      "https://cdn.example.com/event-3.jpg"
    ]
  }'

Can you mix photos and video in one carousel?

Each item in the array can independently be an image or a video — PostGate detects the MIME type per item, so a carousel of two photos and one clip is a normal request, not a special mode. The same per-item limits apply either way: images convert to JPEG (up to 8 MB, width 320–1440px), video up to 1 GB and 5 minutes per clip.

Which limits actually apply?

2 items minimum, 20 maximum. Aspect ratio is unusually permissive for carousel items — Meta accepts anywhere from roughly 1:10 to 10:1 — but each item still has to individually pass the same JPEG-conversion and size checks as a standalone post. PNG source images are silently rejected by the live API despite being listed as supported, so PostGate re-encodes to JPEG before it ever reaches Threads.

How does a carousel count against your quota?

A published carousel — 2 items or 20 — counts as exactly one post toward Meta's 250-posts-per-24-hours limit. That makes carousels the more quota-efficient way to publish multiple images to Threads compared to 20 separate single-item posts. See Threads API rate limits for the full quota behavior.

Frequently asked questions

Can I mix photos and videos in a Threads carousel?

Yes. Each item in the media array can independently be an image or a video — PostGate detects the MIME type per item, so a carousel of two photos and one clip is a normal request, not a special mode. The same per-item limits apply either way: images convert to JPEG (up to 8 MB, width 320–1440px), video up to 1 GB and 5 minutes per clip.

How many items can a Threads carousel have?

Do I need to build Meta media containers myself for a carousel?

No. On Meta's Graph API a carousel is built from individual media containers marked is_carousel_item, wrapped in a parent container with media_type: CAROUSEL. PostGate does this automatically the moment you send more than one item in the media array.

Can each carousel item have its own caption?

No — the caption in post.body is attached to the carousel as a whole, not to individual items. There is one text body per carousel post regardless of how many items it contains.