Log inStart Free Trial
easyCoexistence Official APIs

Instagram carousel posts through the API

Instagram's API publishes a carousel as one post of up to 20 photos and videos under Meta's publishing guide, though its error reference still says 10. Each item gets its own container with is_carousel_item set to true, then a CAROUSEL container lists them as children and carries the caption. Publishing that container posts them together, counting as one of the 100 API-published posts allowed in 24 hours.

easyCoexistence publishes carousels of 2 to 10 photos and videos with publish_instagram_post from Claude, ChatGPT or your own code: one call with the items and the caption publishes the post, and it finishes on its own while a video is still processing.

Up to 20

Photos and videos a carousel can hold under Meta's publishing guide and the children parameter.

2207028

Subcode, under code 100, whose message still says a carousel needs 2 to 10 items.

1 post

What a carousel counts as against the limit of 100 API-published posts in 24 hours.

1:1

Default crop for carousel images, which all follow the aspect ratio of the first image.

0

Insights Meta returns for the individual photos and videos inside a carousel.

How is a carousel published?

In three stages, all through POST /<IG_ID>/media and a single publish call.

  • Items: create a container for each photo (image_url) or video (media_type VIDEO and video_url), with is_carousel_item set to true and no caption.
  • Carousel: create a container with media_type CAROUSEL, children set to the item container IDs separated by commas, and the caption.
  • Publish: POST /<IG_ID>/media_publish with creation_id set to the carousel container's ID.

How many items can a carousel hold?

Up to 20. Meta's publishing guide and the children parameter of POST /<IG_ID>/media both put the limit at 20 images, videos or a mix of the two. The error reference still reads the older way: the message for code 100, subcode 2207028, says a carousel needs at least 2 and no more than 10 items, so 2 to 10 is the count every part of Meta's documentation accepts. Items can be photos or videos, but not Reels: a carousel item is always an image or video container.

How are carousel images cropped?

To the first one. Every image in a carousel is cropped to the aspect ratio of the first image, and the default is a 1:1 square. Each image still has to meet the usual rules: JPEG, up to 8 MB, between 4:5 and 1.91:1. Put the image whose shape you want first, or make them all the same shape before publishing.

What belongs to the carousel and what to each item?

Most post-level settings live on the carousel container, not on the items.

  • Caption: on the carousel container only; items do not take one.
  • Location: on the carousel container only.
  • AI-generated label: is_ai_generated goes on the carousel container, and setting it on an item returns an error.
  • Alt text: supported on image items, up to 1,000 characters each.

How does a carousel read back?

As one media object with media_type CAROUSEL_ALBUM. GET /<IG_MEDIA_ID>/children lists the photos and videos inside it, though some fields, such as permalink, do not work on the children. The carousel's comment and like counts exclude its children, and Meta returns no insights for the individual items, only for the carousel post.

How does a carousel count against the limits?

As one post. An account can publish 100 posts through the API in a moving 24 hours, and a carousel uses one of them however many items it holds. Each item is still a container, though, and an account can create 400 containers in a rolling 24 hours, so a run of ten-item carousels reaches that ceiling before the publishing cap.

Common mistakes

  • Putting the caption on an item. Captions are not supported on carousel items; set it once on the carousel container.
  • Adding a Reel as an item. Carousel items are image or video containers, and a Reel cannot appear in a carousel.
  • Mixing portrait and landscape photos without checking the first one. Every image takes the first image's aspect ratio.
  • Expecting insights per slide. Meta returns none for the media inside a carousel, only for the post.
Doing this with EasyCoexistence

Carousels can be scheduled from its own queue too. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Can an Instagram carousel be scheduled through the API?

Yes, through a queue, since Meta publishes a carousel when its container is published. easyCoexistence's publish_instagram_post takes scheduled_at, from 1 minute to 90 days ahead, for carousels of 2 to 10 items.

Can a carousel be labeled as AI-generated?

Yes, with is_ai_generated on the carousel container. Setting it on an item returns an error.

Can a carousel include a Reel?

No. A Reel is always published on its own, and carousel items are plain image or video containers.

Why does my carousel fail with 2207028?

Meta's message for it says a carousel needs at least 2 and no more than 10 items. A count from 2 to 10 satisfies that message and the publishing guide's limit of 20 alike, so adjust the items and create the carousel container again.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on