Instagram Reels publishing API: a practical guide

Two Instagram APIs, two permission sets

Meta offers two ways to publish to Instagram. Both need an Instagram Business or Creator account.

For accounts you don't own, either flavor needs Advanced Access, which means App Review and Business Verification. See Meta App Review for content publish.

The container flow

1. Create a container. POST to the account's media edge with media_type=REELS, video_url and an optional caption.
2. Wait for processing. GET the container with fields=status_code. Values include IN_PROGRESS, FINISHED, ERROR and EXPIRED. Meta suggests polling once a minute for no more than 5 minutes.
3. Publish. POST the container ID to media_publish. You get back the media ID.
4. Read the permalink. GET the media with fields=permalink to show users the live link.

Meta downloads the video from video_url at processing time, so the URL must be public and fast. Containers not published within 24 hours expire. Meta also offers resumable uploads if you'd rather send the file directly.

Options worth knowing

• Trial Reels. Meta's docs describe trial Reels, shared only with non-followers, created with trial_params. Useful for testing hooks without hitting followers' feeds.
• Grid placement. Whether the Reel also appears on the profile grid.
• Cover. You can choose a cover frame or image.
• Story. Sharing the same video to Stories is a separate Story container.

Video specs

Export 9:16 at 1080x1920, MP4 with H.264 and AAC audio. Check Meta's current Reels specs for duration and file size limits before you batch-export, because they change. If the same clip goes to Facebook Page Reels, keep it between 3 and 90 seconds, which is the range in Meta's Facebook Reels docs.

Common errors

Publishing Reels with UGC API

UGC API runs the container flow for you. You send one request with format: 'video', and the same video can go to TikTok, Facebook and YouTube in the same call.

curl https://ugcapi.dev/v1/posts \
  -H "Authorization: Bearer ugc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["acc_ig_01"],
    "format": "video",
    "media": ["https://cdn.example.com/reels/r-88.mp4"],
    "caption": "The 10-second fix for frizzy hair #hairtok",
    "options": { "instagram": { "grid": true, "story": false } }
  }'

We poll the container, publish it, and send a post.published webhook with the permalink. If Meta returns an error, you get post.failed with platform_rejected and Meta's message. See the errors reference, Instagram posting API and UGC video API.

Scheduling Reels

Meta's Instagram content publishing API has no scheduled publish field for Reels. Scheduling means running your own queue and creating the container close to the publish time, since containers expire after 24 hours. That is one of the pieces UGC API handles: set scheduled_at and we create, poll and publish at the right time. If a container fails or the account hits its limit, you get the reason in the post.failed webhook instead of a silent gap in the schedule.

Checklist before a big batch

1. Every account is Business or Creator.
2. Files are 9:16 MP4 H.264 on fast public URLs.
3. Daily volume per account fits Meta's limit.
4. Your webhook handler stores permalinks and errors.