Instagram Reels API: How to Upload and Publish Reels

There is no separate Reels endpoint

Instagram publishing runs through one content endpoint, and the media type is inferred from what you send rather than declared in a field. Send one video URL and the post is a Reel. Send several image URLs and the post is a carousel. Send one image and it is a single photo. Because the inference comes from the media, the practical rule is one video per request: a payload that carries a video alongside other media has no defined type and is rejected. That design is worth understanding before writing code, because it means you do not add a Reels path to an existing integration. You change the request body from an array of images to an array holding one video URL, and the rest of the publish flow, the status polling, and the analytics read-back stay exactly the same.

• One content endpoint covers photos, carousels, and Reels.
• Media type is detected from the payload, not set in a field.
• One video URL produces a Reel; several image URLs produce a carousel.
• A payload mixing video with other media is rejected.

Account requirements come first

The most common reason a Reel never publishes is the account type rather than the request. Instagram publishing requires a business or creator account connected through Meta OAuth and linked to a Facebook Page. A personal account cannot publish through the API at all, and the failure appears at connection time or on the first publish call rather than as a clear message about account type. Checking this before building saves a debugging session: confirm the account is business or creator and linked to a Page in the connection step, then treat the publish call as the place where media problems surface instead of permissions problems. This requirement is not specific to Reels, but it is discovered through Reels because video is usually the first thing a team tries to automate.

• Business or creator account required; personal accounts cannot publish.
• The account must be linked to a Facebook Page.
• The connection runs through Meta OAuth.
• Check account type at connect time, not at first publish.

The publish request

A Reel request names the Instagram account and sends a single video URL in the media list. The backend fetches that URL, so it has to be reachable from the network rather than behind a local firewall or a signed link that expires in seconds. Give it enough lifetime for the fetch, and prefer a stable URL over a pre-signed one when the platform allows it. The request returns an identifier for the container, and the status endpoint reports when Instagram has finished processing it. Two fields matter for a Reel: the caption, which follows the same length limit as any Instagram post, and the setting that decides whether the Reel also appears in the main feed.

POST /content
{
  "accountId": "your-instagram-account-id",
  "content": "Behind the scenes of this week's build.",
  "mediaItems": [
    "https://cdn.example.com/reels/build-week.mp4"
  ],
  "instagramSettings": {
    "share_to_feed": true
  }
}

share_to_feed, and why it matters

The share_to_feed setting is a boolean that controls whether the Reel is also distributed to the main Instagram feed in addition to the Reels tab. It applies only to single-video posts, which means it is a Reels setting in practice and has no effect on a carousel or a single photo. Leaving it unset is not the same as setting it false on every integration, so decide the default deliberately: a brand that wants maximum reach sets it true, while an account testing a Reels-only strategy may prefer false. Because the field is valid only for video, sending it alongside a photo payload is a validation error rather than a silently ignored value.

Processing is normal, not a failure

A Reel does not appear the moment the publish call returns. Instagram reviews and processes the video, so the status endpoint can report a processing state before it reports published. An integration that treats the first non-published status as an error will retry a request that is working correctly and can end up publishing duplicates. Poll the status endpoint on an interval rather than in a tight loop, treat processing as expected, and only surface an error when the platform reports a failure reason. The same rule applies to the scheduled path: a Reel queued for a future time processes after the queue fires, so the status check belongs after the scheduled time, not at submit.

• Expect a processing state before published.
• Poll on an interval rather than in a tight loop.
• Treat processing as normal; escalate only on a reported failure.
• For scheduled Reels, check status after the scheduled time.

Failures worth handling explicitly

Four failures account for most failed Reel publishes, and each has a different fix. An account that is not business or creator never publishes, and no retry helps. A video URL the backend cannot fetch fails at the media step even when the URL works in a browser. A payload that mixes a video with other media is rejected by validation. And a video outside the platform duration or format rules is refused after upload, which is the most expensive failure to debug because the request looked correct. Checking those four conditions before the request, and reading the reason on the ones that still fail, turns a frustrating integration into a short checklist.

Where Reels fit in a multi-platform workflow

The reason Reels belong in the same integration as the rest is that the video is usually already being published elsewhere. A team producing a vertical video for TikTok or YouTube has a file that also suits Instagram, and the profile is close to identical: vertical orientation, H.264, and a duration inside the short-form window. Publishing it through the same endpoint means one media preparation step serves three platforms, and the status check is the same call for each. What differs is only the per-platform settings block, which is where share_to_feed and the other account-level options live. Building the workflow with a shared media step and per-platform settings is what keeps five platforms from becoming five integrations.