Posts

Publish a carousel on Instagram via API

With format feed and several media items, Connect publishes a carousel on the Instagram account your customer connected. There is no Meta app review and no token handling: it is one call, the same for every connected account.

The request

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "post-4410",
  "format": "feed",
  "caption": "Nova coleção no ar #verao",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/1.jpg",
      "alt_text": "Vestido azul",
      "user_tags": [
        {
          "username": "marca_parceira",
          "x": 0.5,
          "y": 0.4
        }
      ]
    },
    {
      "type": "video",
      "url": "https://cdn.example.com/2.mp4"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/3.jpg"
    }
  ]
}

What you can do

  • Publish a carousel of 2 to 10 images and videos, in the order they appear in media.
  • Mix images and videos in the same carousel.
  • Tag users on each media with media[].user_tags, with x and y position on images.
  • Send alt text for each media with alt_text.
  • Add collaborators, a first comment and a location in the instagram block.

Rules and limits

  • Feed takes 1 image or a carousel of 2 to 10 images and videos. A single video is not feed: use reels.
  • The caption goes up to 2200 characters, with at most 30 hashtags and 20 mentions.
  • Each media takes up to 20 user_tags. On an image, x and y (from 0 to 1) go together or not at all; on a video, no x and y.
  • A carousel from an account connected through Instagram Login does not accept user_tags.
  • The answer is 202: the post is stored and published in the background. Follow it with GET /posts/{uuid}.
  • external_reference is required and prevents publishing the same post twice (409). The Idempotency-Key header makes retries safe.

Main fields

FieldTypeRequiredDescription
external_referencestringYesThe post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account.
formatstringYesPost format. On Instagram: feed, reels or story. On Facebook: feed, reels or story.
captionstringNoCaption. On Instagram, up to 2200 characters, 30 hashtags and 20 mentions. Stories carry no caption.
mediaarrayYesList of media, in order. Each item has type and url.
media.typestringYesMedia type: image, video or document (document is LinkedIn only).
media.urlstringYesPublic https:// URL the network can download (up to 2048 characters).
media.alt_textstringNoAlt text for the media, up to 1000 characters.
media.user_tagsarrayNoInstagram only. User tags (username, x and y), up to 20 per media. On an image, x and y from 0 to 1 go together.

Who it is for

  • Social scheduler inside your SaaS

    The user builds the carousel in your editor and your backend publishes it with one POST /posts on the Instagram account they connected.

  • E-commerce launches

    Generate a carousel from catalog photos and tag the partner brand on each image when the launch goes live.

  • Content AI agent

    An agent creates the images and caption and publishes the carousel on its own, using external_reference to never duplicate.

Works with

  • Instagram Business
  • Instagram

Frequently asked questions

How many images fit in a carousel?

From 2 to 10 media items, images and videos, in the feed format. A single image is also feed; a single video must go as reels.

Do I need Meta app review?

No. The customer connects the account once and you publish through Connect, sending only the merchant Bearer and the x-customer-token.

How do I know the carousel was published?

POST /posts answers 202 and publishing runs in the background. Check GET /posts/{uuid}: the status goes through created, publishing, published or failed, and on failure publishing.error carries code and message.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.