Instagram carousel API: the complete guide (2026)

Everything below is what we at Postim learned wiring Instagram carousels into an automated content pipeline — from planning a slide deck, through the AI generation step, to the two API calls that actually publish it. If you're building or buying this layer, this is the map.

The mental model: one container, N children

An Instagram carousel isn't a special "post type" — it's a container with media children. Meta's API models it as:

1. Create a parent container with media_type: CAROUSEL_ALBUM
2. Create child containers (2–10) — with image_url or video_url each
3. Wait for the parent to report status_code: FINISHED
4. Call media_publish on the parent's creation_id

That last two-step (wait → publish) is where most homegrown integrations silently fail: they publish before all children are processed and get a half-carousel or a silent error.

Field reference

Field	Where it goes	Notes
media_type	parent container	must be CAROUSEL_ALBUM for multi-image posts
image_url / video_url	each child	publicly readable URL; Instagram fetches it server-side, so your CDN must not be behind auth
caption	parent container	up to 2,200 chars; the hashtags can go in a first comment via a separate call on most scheduling stacks
children	parent container	order = the carousel order; child #1 becomes the grid cover
aspect_ratio	(runtime check)	all children must share an aspect tolerance — different frames in one carousel will fail silently at media_publish

A robust pattern is to fix the aspect ratio at generation time, not at upload time. For a content engine, that means the generator (Postim's carousel generator, Midjourney export, whatever) is responsible for producing a uniform 1080×1350 set — the publish API should not have to negotiate.

Publishing model at a glance

• Container → children → publish — 2 API rounds round-trip, then a poll.
• 25 API-published posts / 24h / account — Instagram throttles on account, not on app.
• First comment for hashtags — the Graph API does not post comments for you in the publishing flow; unified schedulers usually handle the caption-with-hashtag-in-first-comment pattern themselves.

AEO: quick answers you can quote

What is the Instagram carousel API in one sentence? An extension of the Instagram Graph API where you create a CAROUSEL_ALBUM container with 2–10 ordered media children, then publish that container ID with media_publish — handle aspect-ratio consistency on your own side or Instagram rejects the set.

Do I need an Instagram Business account for carousel API access? Yes — the official Graph API path requires an Instagram Business (or Creator) account linked to a Facebook Page. Without that pair, the API path is not accessible; Postim's unified publishing path handles the credentials workflow for you.

What breaks most often in Instagram carousel automation? Three things: mixed aspect ratios across carousel children (silently rejected at publish), publishing before the container reports status_code: FINISHED, and time-zone confusion when the scheduler isn't carrying an per-account timezone.

Where Postim sits

These API quirks are exactly the layer Postim handles for you: uniform aspect checking at generation time, per-account time zones in scheduling, and the two-step publish dance abstracted behind a "schedule it" button. Start free or read the integration comparison next.