How-to guide • Published May 6, 2026

How to Publish an Instagram Carousel via API

Instagram carousels need N child containers, one carousel container, and a publish call. Postproxy collapses it to one POST.

What the carousel flow looks like in raw Graph API

For a 5-image carousel:

1. POST /{user-id}/media (image_url=..., is_carousel_item=true)  → child_1
2. POST /{user-id}/media (image_url=..., is_carousel_item=true)  → child_2
3. POST /{user-id}/media (image_url=..., is_carousel_item=true)  → child_3
4. POST /{user-id}/media (image_url=..., is_carousel_item=true)  → child_4
5. POST /{user-id}/media (image_url=..., is_carousel_item=true)  → child_5
6. (optional) GET each child's status_code until FINISHED
7. POST /{user-id}/media (media_type=CAROUSEL, children=[child_1,...,child_5])  → parent
8. (optional) GET parent status_code until FINISHED
9. POST /{user-id}/media_publish (creation_id=parent)  → live

Seven to nine round trips. If step 5 fails, you’ve created four orphan containers that count against the 50-pending-container limit. If step 9 fails after the parent is built, retrying the publish with the same parent ID is safe — but if your code re-runs from the top, you build another parent and publish a duplicate.

This is the kind of multi-step flow that benefits from a wrapper.

With Postproxy: one POST

curl -X POST "https://api.postproxy.dev/api/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post": { "body": "Five things we learned shipping our SDK this week ↓" },
    "profiles": ["instagram"],
    "media": [
      "https://yourcdn.com/tip-1.jpg",
      "https://yourcdn.com/tip-2.jpg",
      "https://yourcdn.com/tip-3.jpg",
      "https://yourcdn.com/tip-4.jpg",
      "https://yourcdn.com/tip-5.jpg"
    ],
    "platforms": {
      "instagram": {
        "format": "post",
        "first_comment": "Code samples for each tip in the comments below ↓"
      }
    }
  }'

Postproxy creates the children in parallel, waits for processing, builds the parent, and publishes. If a child fails along the way, Postproxy retries only what’s needed — the failed step, not the whole carousel. You don’t have to think about it: one POST in, one published carousel out.

format: "post" is the carousel/feed format. Multi-image media in a feed post is a carousel by default.

Specs and limits

Children: 2 to 10 items
Image: JPG or PNG, max 8 MB per item, min 200×200
Video: MP4 or MOV, max 300 MB per item, 3s–60min
Mixed images and videos: allowed
Aspect ratio: must be consistent across children — Instagram crops/letterboxes to match the first item
Caption (post.body): max 2,200 characters
first_comment: max 2,196 characters

Mixed media carousel (images + video)

curl -X POST "https://api.postproxy.dev/api/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post": { "body": "Behind the scenes of our latest product video.\n\nSwipe for stills + the final cut." },
    "profiles": ["instagram"],
    "media": [
      "https://yourcdn.com/bts-still-1.jpg",
      "https://yourcdn.com/bts-still-2.jpg",
      "https://yourcdn.com/bts-still-3.jpg",
      "https://yourcdn.com/final-cut.mp4"
    ],
    "platforms": {
      "instagram": { "format": "post" }
    }
  }'

Postproxy uses the right media_type per child container automatically.

Cross-post the carousel to LinkedIn and Threads

LinkedIn supports up to 20 images per post. Threads supports up to 20 children with mixed media. Same call:

curl -X POST "https://api.postproxy.dev/api/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post": { "body": "Five lessons from shipping v3 ↓" },
    "profiles": ["instagram", "linkedin", "threads"],
    "media": [
      "https://yourcdn.com/tip-1.jpg",
      "https://yourcdn.com/tip-2.jpg",
      "https://yourcdn.com/tip-3.jpg",
      "https://yourcdn.com/tip-4.jpg",
      "https://yourcdn.com/tip-5.jpg"
    ],
    "platforms": {
      "instagram": { "format": "post" }
    }
  }'

For platform differences and edge cases, see Publishing carousel posts across Instagram, LinkedIn, and Threads via API.

Scheduling a carousel

curl -X POST "https://api.postproxy.dev/api/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "body": "Year in review: the 10 features we shipped that mattered.",
      "scheduled_at": "2026-12-31T15:00:00Z"
    },
    "profiles": ["instagram"],
    "media": [
      "https://yourcdn.com/yir-01.jpg",
      "https://yourcdn.com/yir-02.jpg",
      "https://yourcdn.com/yir-03.jpg",
      "https://yourcdn.com/yir-04.jpg",
      "https://yourcdn.com/yir-05.jpg",
      "https://yourcdn.com/yir-06.jpg",
      "https://yourcdn.com/yir-07.jpg",
      "https://yourcdn.com/yir-08.jpg",
      "https://yourcdn.com/yir-09.jpg",
      "https://yourcdn.com/yir-10.jpg"
    ],
    "platforms": {
      "instagram": { "format": "post" }
    }
  }'

Postproxy creates the containers near publish time — no need to worry about the 24-hour container expiry.

Why one POST is the right shape

Carousels are exactly the kind of API where the official Graph API’s surface area pushes complexity onto your code. Wrapping it once means application code goes from ~150 lines of polling and orphan-handling to a single HTTP call. The deeper walkthrough lives in Publishing carousel posts across Instagram, LinkedIn, and Threads via API.