Publishing an Instagram Story through the API

How do you publish an Instagram Story through the API?

Story media specifications

Neither the SDK nor the dashboard can check these — Meta fetches the file on its own side. A mismatch pushes the container into ERROR.

yesno

PNG and WebP are rejected — convert to JPEG first. If the URL needs authentication or has expired, Meta cannot fetch the file.

The raw requests: container and publish

The flow is identical without an SDK. The first response returns the container id, which becomes creation_id in the second request.

# 1) Story container
curl -X POST "https://graph.facebook.com/v26.0/$IG_ID/media" \
  -d "image_url=https://cdn.example.com/story.jpg" \
  -d "media_type=STORIES" \
  -d "access_token=$TOKEN"
# -> {"id":"17998...."}

# 2) For video, wait until the container is ready
curl -G "https://graph.facebook.com/v26.0/17998...." \
  -d "fields=status_code" -d "access_token=$TOKEN"
# -> {"status_code":"FINISHED"}

# 3) Publish
curl -X POST "https://graph.facebook.com/v26.0/$IG_ID/media_publish" \
  -d "creation_id=17998...." -d "access_token=$TOKEN"

Why a story container has no caption

Permissions for both login paths

Instagram has two authorisation paths with completely different scopes. A Facebook Page is required on only one of them.

On the Facebook Login path, ads_management or ads_read is also needed when the Page role was granted through Business Manager.

Who can read the list of active stories

The daily limit: Meta's own docs give two numbers

Publishing a story with the Socialift SDK

The SDK folds container creation, waiting and publishing into one call and returns container_id and media_id.

import asyncio, os
from socialift import ContainerNotReadyError, Instagram

CDN = "https://cdn.example.com"

async def main():
    token = os.environ["IG_USER_TOKEN"]
    async with Instagram.from_env() as ig:
        photo = await ig.publish_story(token, image_url=f"{CDN}/story.jpg")
        try:
            clip = await ig.publish_story(token, video_url=f"{CDN}/story.mp4", wait_timeout=120.0)
        except ContainerNotReadyError as exc:
            print("container not ready yet:", exc.container_id)
            return
        active = await ig.stories(token, limit=25)
        print(photo["media_id"], clip["media_id"], len(active))

asyncio.run(main())

Facebook Page stories: photo and video flows

Page stories do not use Instagram's container flow at all — they have two protocols of their own.

1. 1

   Photo: upload it unpublished first

   The photo_stories edge takes only photo_id and refuses a URL. So the first call is POST /<PAGE_ID>/photos?published=false&url=<link>, which returns just an id and keeps the photo out of the feed.

2. 2

   Photo: publish it as a story

   Pass that id to POST /<PAGE_ID>/photo_stories?photo_id=<id>. An unpublished photo stays on Facebook's servers for roughly 24 hours, after which the photo_id stops working.

3. 3

   Video: start the session

   POST /<PAGE_ID>/video_stories?upload_phase=start returns video_id and upload_url. That upload_url points at rupload.facebook.com and must be taken from the response, never assembled by hand.

4. 4

   Video: upload the file

   POST to that upload_url. Here the token travels in an Authorization: OAuth <token> header, not in the query. With a link you send a file_url header and an empty body; with a file you send offset and file_size headers and the bytes as the body.

5. 5

   Video: finish

   POST /<PAGE_ID>/video_stories?upload_phase=finish&video_id=<id>. Before that, wait until uploading_phase.status == "complete" via GET /<VIDEO_ID>?fields=status.

Page stories: SDK example and resumed uploads

The SDK runs both flows internally: two steps for a photo, three for a video, plus resuming an interrupted upload.

import asyncio, os
from socialift import Facebook

async def main():
    page_id = os.environ["FB_PAGE_ID"]
    page_token = os.environ["FB_PAGE_TOKEN"]
    async with Facebook.from_env() as fb:
        photo = await fb.publish_photo_story(
            page_id, page_token, photo_url="https://cdn.example.com/story.jpg"
        )
        clip = await fb.publish_video_story(
            page_id, page_token, video="/srv/media/story.mp4", upload_attempts=3
        )
        state = await fb.video_story_status(clip["video_id"], page_token)
        print(photo["post_id"], state.get("publishing_phase"))

        for item in await fb.stories(page_id, page_token, limit=25):
            print(item["post_id"], item["status"])

asyncio.run(main())

Common mistakes and how to avoid them

• ▸The image is PNG or WebP — Instagram stories accept JPEG only.
• ▸A signed URL has expired or asks for a login — Meta fetches the file at call time.
• ▸media_publish was called before the video container reached FINISHED.
• ▸Both image_url and video_url were sent in one container.
• ▸You expect a caption or a sticker — the API adds neither.
• ▸GET /<IG_ID>/stories was called with an Instagram Login token, where the edge does not exist.
• ▸The daily limit is hard-coded — read it from content_publishing_limit instead.
• ▸A Page story video is below 540p — that error surfaces in the status after the upload, not at the finish step.
• ▸A Page photo sat unpublished for more than a day: the photo_id has expired.