Instagram Stories API
What the Instagram API actually supports for Stories — format, duration, and the real limits on scheduling them.
By André LugYes — Meta’s Content Publishing API has supported Instagram Stories since 2023 via the container flow, with media_type set to STORIES. Through PostGate, set options.instagram.mode to "story" with exactly one vertical (9:16) media item. There is no native “publish later” for Stories — scheduling means a layer holds the request and fires the publish call at the right instant.
Stories are the one format where it's worth checking, before you build anything, whether the API even supports what you're picturing. Meta's Instagram Content Publishing API has supported Stories since 2023 through the container flow — but with a hard vertical-format requirement and no native "publish later" field, which changes what "scheduling a Story" actually means in practice.
Are Stories supported via the API?
Instagram creates a Story container the same way it creates any other container, with media_type set to STORIES instead of IMAGE or VIDEO. Facebook Pages have their own, separate Stories endpoints. This is confirmed in Meta's own content-publishing documentation. Not every platform PostGate connects to has equivalent support — LinkedIn, Threads, and Pinterest do not expose Stories-equivalent publishing through their public APIs at the time of writing, so confirm current platform support before assuming a format carries over.
How strictly are vertical format and duration enforced?
Stories are consumed full-screen vertical (9:16). A horizontal asset sent without adaptation renders cropped or letterboxed rather than rejected outright — which is arguably worse, since it publishes looking wrong instead of failing loudly. Video Stories also carry a per-segment duration limit; a longer video is split into sequential Stories automatically by the platform rather than uploaded as one continuous clip. Validate aspect ratio and duration before you send the asset, not after a customer notices the result.
How do I publish a Story via PostGate?
Set options.instagram.mode to "story" on the same post envelope used for a feed post, with exactly one media item — neither Instagram nor Facebook accepts a carousel of Stories in a single publish call.
curl -X POST "https://api.postgate.studio/api/posts" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ig-story-launch-01" \
-d '{
"post": { "options": { "instagram": { "mode": "story" } } },
"profiles": ["pro_instagram123"],
"media": ["https://cdn.example.com/story-vertical.jpg"]
}'What does "scheduling" a Story actually mean?
This is the least obvious part: Instagram's publish call for a Story executes immediately, the same as any other container — there is no scheduled_publish_time equivalent on the Stories path. When PostGate accepts a scheduled_at value for a Story, it is holding the request and firing the real publish call at the right instant, not configuring Instagram to publish on its own later. Any tool that markets "Story scheduling" is doing the same thing under the hood. The practical consequence: if the scheduling layer itself goes down at the exact scheduled minute, the Story simply does not go out, because the platform never knew it existed before that moment.
When does the 24-hour clock start?
A Story's expiry is measured from the moment it actually goes live on Instagram, which is exactly why the scheduling mechanics above matter — a delayed publish call does not shorten the Story's visible lifetime, but it does mean the Story appears later than the customer expected relative to whatever they scheduled it against.
Frequently asked questions
Does the Instagram API support publishing Stories?
Yes — since 2023, through the same container flow as other formats, with media_type set to STORIES instead of IMAGE or VIDEO. Facebook Pages have their own, separate Stories endpoints. Not every platform has an equivalent: LinkedIn, Threads, and Pinterest do not expose Stories-equivalent publishing through their public APIs at the time of writing.
What happens if I send a horizontal asset as an Instagram Story?
It renders cropped or letterboxed rather than being rejected outright — arguably worse, since it publishes looking wrong instead of failing loudly. Stories are consumed full-screen vertical (9:16), so validate aspect ratio and duration before you send the asset, not after a customer notices the result.
Can I publish multiple Stories in one API call?
No — a Story publish takes exactly one media item; neither Instagram nor Facebook accepts a carousel of Stories in a single publish call. A video longer than the per-segment duration limit is split into sequential Stories automatically by the platform rather than uploaded as one continuous clip.
Can Instagram Stories be scheduled via API?
Not natively — the publish call for a Story executes immediately, with no scheduled_publish_time equivalent on the Stories path. When PostGate accepts scheduled_at for a Story, it holds the request and fires the real publish call at the right instant; any tool that markets “Story scheduling” does the same under the hood. If the scheduling layer itself is down at that exact minute, the Story simply does not go out.
When does a Story’s 24-hour clock start?
At the moment it actually goes live on Instagram, not at creation. A delayed publish call does not shorten the Story’s visible lifetime — but it does mean the Story appears later than the customer expected relative to whatever they scheduled it against.
