Send two or more mediaItems to an Instagram or Threads target and they publish as a single
carousel, in array order. There is no separate endpoint and no extra flag.
How it is built
For each carousel target Chirio:
Creates one child container per media item, in array order.
Polls every child until it finishes processing (video children can take minutes).
Creates the parent CAROUSEL container referencing the children, carrying the caption.
Publishes the parent.
The order of mediaItems is the slide order the reader swipes through.
A carousel is atomic per target
One bad child fails the whole target
If any child container fails to process, that target fails as a whole — there is no partial carousel. Other targets in the same request are unaffected, so a broken image can fail Instagram while Threads publishes normally.
This is the right failure mode: a carousel missing its third slide is worse than no post at
all, and republishing over a partial one is not something an API can do for you.
Limits
Platform
Carousel range
Caption
Notes
Instagram
2–10 items
2,200 chars
Images must be JPEG; video children are allowed
Threads
2–20 items (10 in practice)
500 chars
Request-level cap of 10 media items binds first
A single video on Instagram publishes as a Reel, not a one-slide carousel — that is Meta's
behaviour, and media_type=REELS is single-video only, which is why carousel video children
use VIDEO instead.X and LinkedIn have no carousel concept. Multiple images there publish as X's up-to-4 image
post and LinkedIn's multi-image post respectively — see Media.
Timing
Children process in parallel on Meta's side, but each is polled until terminal, so a carousel
takes as long as its slowest item. Video-heavy carousels can take several minutes.Always send an Idempotency-Key on a carousel publish. A timeout on your side is otherwise
indistinguishable from a failure, and retrying without a key risks a duplicate carousel.
