# Instagram carousels through the API: the limits nobody documents together

If you have ever built against the Instagram Graph API, you already know the
documentation is spread across four pages that never quite agree. Carousels are
the worst of it: the limits, the container lifecycle and the failure modes are
each documented somewhere, and never in the same place.

Here is the whole thing in one page.

## A carousel is three API calls, not one

There is no endpoint that takes an array of images. Publishing a carousel is:

1. **One container per slide.** `POST /{ig-user-id}/media` with `image_url` (or
   `video_url`) and, critically, `is_carousel_item=true`.
2. **One parent container.** `POST /{ig-user-id}/media` with
   `media_type=CAROUSEL`, the caption, and `children` set to the comma-separated
   list of child container ids.
3. **Publish.** `POST /{ig-user-id}/media_publish` with the parent's id.

Miss `is_carousel_item=true` on a child and Meta happily creates a normal
single-image container. You will not find out until step two rejects it.

## Ten slides, not twenty

The app lets someone swipe together twenty images. The API stops at ten.

This catches people out because it is a product limit expressed as an API
error, and the error does not say "the app allows more". If your source of truth
is what you can do on your phone, you will build a feature that fails for your
users on the eleventh slide.

There is no flag, permission or review process that raises it.

## Containers are asynchronous, and that is the real work

The call that creates a container returns an id immediately. The container is
not ready.

```
GET /{container-id}?fields=status_code
```

`status_code` moves through `IN_PROGRESS` to `FINISHED`, or to `ERROR`. You
cannot publish until every child and the parent report `FINISHED`. Publishing
early returns an error about media not being ready, which reads like a bug in
your code and is actually a race you have to wait out.

For images this is usually a second or two. For video it can be minutes, and a
carousel mixing both is as slow as its slowest video.

### Polling has to have a budget

This is the part that turns a working integration into a broken one at 3am.

If you poll forever, a stuck container holds a worker open. If your scheduler
also has a "this job looks stuck, reclaim it" timeout, and your polling budget
is longer than that timeout, a second worker picks up the same post while the
first is still waiting. Both eventually publish. The customer gets the same
carousel twice, on their real audience, and there is no undo.

The fix is arithmetic, not cleverness: **your total polling budget must be
comfortably less than your stuck-job timeout.** Half is a reasonable choice. If
your scheduler reclaims after five minutes, stop polling at two and a half and
fail the job cleanly.

## What to do when a slide fails

A child container that reaches `ERROR` cannot be repaired. The parent cannot be
created without it, and the ids are not reusable.

The honest behaviour is to fail the whole post with a message naming the slide,
rather than publishing a carousel with a hole in it. A four-slide carousel
posted as three slides is not a partial success; it is a different post, and
usually one the author would not have approved.

## The short version

Build the children, wait for all of them, build the parent, wait for it,
publish. Cap at ten. Budget your polling against your own reclaim timeout, not
against Meta's patience.

Everything else about Instagram publishing is easier than this.