Instagram Carousel API
How to publish a multi-image or mixed photo/video carousel to Instagram via API, up to the platform limit per post.
By André LugAn Instagram carousel is a container of containers: the Graph API creates each child image or video as its own item container, then wraps their IDs into a parent carousel container capped at 10 items. Through PostGate, attach an array of media URLs to one POST /api/posts request — it builds the item containers, the parent, and the publish step for you.
A carousel is the one Instagram post type that is structurally different from every other container type — it is a container of containers. Instagram's Graph API creates each child image or video as its own item container first, then wraps their IDs into a parent carousel container. This page covers that structure and the one hard limit that trips people up: how many items actually fit.
How do I publish multiple media in one request?
PostGate hides the child-container step. Attach an array of media URLs to a single post and PostGate builds each item container, then the parent carousel container, then publishes it as one unit.
curl -X POST "https://api.postgate.studio/api/posts" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ig-carousel-launch-01" \
-d '{
"post": { "body": "Swipe through the whole collection." },
"profiles": ["pro_instagram123"],
"media": [
"https://cdn.example.com/item-1.jpg",
"https://cdn.example.com/item-2.jpg",
"https://cdn.example.com/item-3.mp4"
]
}'Is the 10-item limit really enforced?
Meta's Graph API documentation caps a carousel's children array at 10 image or video containers, mixed freely between the two. This is not a soft or configurable limit — an 11th item is rejected at the parent-container step, not silently dropped. If you attach more than 10 media items to a single post targeting Instagram, expect that Instagram target specifically to fail while other platforms in the same request succeed.
Can photos and videos share one carousel?
Unlike a standalone post, a carousel does not require every item to be the same media type — a photo and a video item container can sit side by side in the same children array. Each item still goes through its own validation and processing individually before the parent container can be published, so one bad asset in the middle of an otherwise-valid set can hold up the whole carousel.
Can a carousel partially publish?
Because the parent container is what actually gets published, a carousel is atomic on Instagram's side — either the whole set of items goes live as one post, or none of it does. That is different from PostGate's partial status, which describes one post reaching multiple platforms with mixed outcomes across targets, not mixed outcomes within a single carousel's items.
Frequently asked questions
How many items fit in an Instagram carousel via API?
10. Meta’s Graph API documentation caps a carousel’s children array at 10 image or video containers, mixed freely between the two. It is not a soft or configurable limit — an 11th item is rejected at the parent-container step, not silently dropped.
Can an Instagram carousel mix photos and videos?
Yes — unlike a standalone post, a carousel does not require every item to be the same media type; a photo and a video item container can sit side by side in the same children array. Each item still goes through its own validation and processing individually, so one bad asset in the middle of an otherwise-valid set can hold up the whole carousel.
Can an Instagram carousel partially publish?
No. Because the parent container is what actually gets published, a carousel is atomic on Instagram’s side — either the whole set of items goes live as one post, or none of it does. PostGate’s partial status is different: it describes one post reaching multiple platforms with mixed outcomes across targets, not mixed outcomes within a single carousel’s items.
What happens if I attach more than 10 media items to a post targeting Instagram?
Expect that Instagram target specifically to fail while other platforms in the same request succeed — the excess is rejected at Instagram’s parent-container step rather than trimmed.
