Publishing Instagram Stories through the API
Instagram's API publishes a Story from one image or one video at a public URL: create a container with media_type STORIES, then publish it. Images are JPEG up to 8 MB, videos run 3 to 60 seconds and up to 100 MB, Meta recommends a 9:16 frame, and the Story disappears after 24 hours, as in the app.
easyCoexistence publishes image and video Stories with publish_instagram_post from Claude, ChatGPT or your own code, and can schedule them from its own queue.
Longest Story video the API publishes; the shortest is 3 seconds, and the file can reach 100 MB.
Largest Story image, which has to be a JPEG.
How long a published Story stays up before it expires.
Story metric values this low come back as error 10, not enough viewers, instead of a number.
How is a Story published?
With the same two calls as any post. POST /<IG_ID>/media with media_type set to STORIES and either image_url or video_url, then POST /<IG_ID>/media_publish with the container ID. A video Story is processed first, so its container's status_code has to read FINISHED before it can be published.
Meta's reference describes the caption for photos, videos and carousels, not for Stories, so words meant for the viewer belong in the image or video itself.
What are the Story media requirements?
Meta recommends a 9:16 frame for Story images and videos alike, to avoid cropping or blank space.
- Image: JPEG, up to 8 MB, in sRGB; other color spaces are converted.
- Video: MOV or MP4 with H.264 or HEVC video and AAC audio, 23 to 60 frames per second, up to 1920 pixels wide and 25 Mbps.
- Video length: 3 to 60 seconds, with a file of up to 100 MB.
- Video aspect ratio: anything from 0.1:1 to 10:1 is accepted.
What can a Story carry?
The image or video itself, and mentions of other accounts: since July 2025 the user_tags parameter tags public accounts in image and video Stories, with x and y coordinates optional. Meta does not support publishing stickers through the API, so links, polls and locations stay in the app.
What happens after a Story is published?
It stays up for 24 hours and then expires, as in the app. Meta lists live Stories on a separate stories edge; the account's media list, GET /<IG_ID>/media, does not include them. Read back, a Story's media_type is IMAGE or VIDEO, the same as any other media, so tell Stories apart by where you found them rather than by their type.
How do replies and mentions come back?
As direct messages. A reply to a Story reaches the account as a DM on the messages webhook, with the Story's ID and URL attached, and it opens the usual 24-hour window for a reply. When someone mentions the account in their own Story, that arrives as a message too, with an attachment of type story_mention. Meta's Mentions API does not cover Stories.
Which metrics does a Story report?
Reach, views, shares, replies, follows, profile visits, profile activity, navigation, link clicks, reposts and total interactions, read through the media insights endpoint. They are available for 24 hours only, and a value under 5 returns error code 10, not enough viewers, instead of a number. Replies from people in Europe and Japan are left out of the count, and a Story created by an account there reports 0 replies.
Common mistakes
- Planning a link sticker. The API does not publish stickers, so a link has to reach people another way, such as a DM reply.
- Reading Story metrics the next day. They are available for 24 hours only, so collect them while the Story is up.
- Looking for a published Story in the account's media list. Live Stories are listed on a separate stories edge.
- Publishing a landscape video as a Story. Meta recommends 9:16, and other shapes can show blank space or get cropped.
Replies to a Story arrive as DMs, which can be forwarded to your endpoint or get a reply from an automation. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Can I add a link sticker to a Story through the API?
No. Meta does not support publishing stickers through the API, links, polls and locations included. Mentioning another account without a sticker is supported.
Where is a published Story listed in the API?
On the account's separate stories edge while it is live. GET /<IG_ID>/media does not include Stories, and a Story reads back as IMAGE or VIDEO.
Can a Story have a caption through the API?
No. Meta's reference describes no caption for Stories, and publish_instagram_post sends a Story without one, so words meant for the viewer go in the image or video itself.
How long are Story insights available?
For 24 hours. Meta makes Story metrics available only for that long, so read them while the Story is up.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on