How to post an Instagram Story via API

How Meta's API publishes a Story

Instagram content publishing uses containers. To post a Story directly with Meta's API you:

1. Create a media container on the Instagram account with media_type=STORIES and an image_url or video_url.
2. Poll the container's status_code until it is FINISHED. Meta suggests checking about once a minute, for up to 5 minutes. Containers expire if not published within 24 hours.
3. Call media_publish with the container ID.

Meta fetches the media from your URL at publish time, so the file must be publicly reachable. Your app also needs the content publish permission, which means App Review for accounts you don't own. See our Meta App Review guide.

Requirements

• An Instagram Business or Creator account. Personal accounts can't publish via the API.
• Images as JPEG. Videos as MP4 with H.264.
• A 9:16 frame, 1080x1920, for full-screen Stories.
• Room in the account's publishing limit. Stories count toward Meta's per-account cap on API-published posts in a rolling 24 hours.

What the API can't do

• Add interactive stickers: links, polls, questions, mentions, music.
• Add Stories to Highlights.
• Post to a personal account.

Design the call to action into the frame itself, such as 'New post, tap my profile'. If you need link stickers, the creator has to add them in the app.

Post a Story with UGC API

UGC API wraps the container flow. You add instagram.story: true to a post and we handle containers, polling and publishing.

await fetch("https://ugcapi.dev/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.UGCAPI_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accounts: ["acc_ig_01"],
    format: "video",
    media: ["https://cdn.example.com/ugc/clip-55.mp4"],
    caption: "Day 7 of the 30-day test",
    options: { instagram: { grid: true, story: true } },
  }),
});

This posts a Reel on the grid and the same video as a Story: 2 credits.

Story sequences from a slideshow

There is no multi-frame Story object in Meta's API. A sequence is several Story media published in order. With format: 'slideshow' and story_slides: 'all', we publish one frame per slide in slide order, after the carousel. With story_slides: 'first', only the first slide goes to Stories, which works as a teaser for the carousel.

{
  "accounts": ["acc_ig_01"],
  "format": "slideshow",
  "media": ["https://cdn.example.com/s/1.jpg", "https://cdn.example.com/s/2.jpg", "https://cdn.example.com/s/3.jpg", "https://cdn.example.com/s/4.jpg", "https://cdn.example.com/s/5.jpg"],
  "caption": "5 outfits for one trip",
  "options": { "instagram": { "story": true, "story_slides": "all" } }
}

Credits: 1 for the carousel plus 5 Story frames, so 6. Those 6 also count toward the account's daily publishing limit.

Designing Story frames

1. Keep text and faces out of the top 250px and bottom 250px. Instagram draws the progress bar, profile name and reply bar there.
2. Make each frame readable in about 5 seconds, the default image Story duration.
3. Number frames ('1/5') in a sequence so viewers know to keep tapping.
4. End with a frame that tells people where to go next.

Picking all frames or just the first

For more on formats, see the Instagram Story API page and the full option list in formats and options. Daily caps are covered in limits.

Scheduling Stories well

Stories last 24 hours from the moment they publish, so the scheduled time is also the start of the Story's life. Post when the account's followers are active, and avoid stacking several sequences in the same hour, because the tray only shows the account once. If the same slides also go out as a carousel, a Story teaser right after the carousel sends people to it while it's fresh. For heavy days, count frames against the account's daily publishing allowance first. A creator running a Reel, a carousel and a 10-frame sequence uses 12 items in one day.