Post Stories via API to Instagram and Facebook
Stories are ephemeral posts that disappear after 24 hours. OmniSocials supports stories on Instagram and Facebook. Snapchat stories are on the roadmap.
Stories use the same POST /posts/create endpoint as regular posts. The difference is type: "story" and the fact that media is required. A story can carry up to 10 slides: every media item you pass is one slide, and each slide publishes as its own story on the platform, in the order given.
Supported channels
| Channel ID | Platform | Supported |
|---|---|---|
instagram | ✅ | |
facebook | ✅ | |
snapchat | Snapchat | coming soon |
Calling POST /posts/create with type: "story" and a channel that does not support stories (LinkedIn, X, Pinterest, etc.) returns 400.
Minimal example
Terminal
Stories always require at least one media file. A story request with no media_ids and no media_urls returns 400.
Multi-slide stories
Pass several media items to publish several slides in one post. The order of the array is the publish order.
JSON
How it works:
- Instagram and Facebook have no multi-slide story container. OmniSocials publishes one story per slide, one after the other, so they appear in sequence on the profile.
- Max 10 slides per platform. More than 10 returns
400 validation_error. - Each video slide is limited on its own (60 seconds, see Media requirements). A validation error names the slide that is over the limit.
- If a slide fails, the slides before it stay live. A retry (
POST /posts/{id}/retry) publishes only the slides that did not go out. No slide is published twice. - Each slide publish counts toward Instagram's 100 API publishes per 24 hours.
After publishing, the post carries a story_slides field with every slide per platform, in publish order:
JSON
published_urls keeps the first slide per platform, so existing integrations keep working. GET /analytics/posts/{id} returns the summed metrics per platform plus a story_slides array with each slide's own metrics.
Text on stories
Stories do not have captions the way feed posts do. The content field is optional on stories and, when provided, is used as internal notes in your OmniSocials dashboard. It is not rendered on the published story.
If you want text to appear on the story visual itself, bake it into the image or video before uploading. OmniSocials does not composite text onto media at publish time.
Cross-posting a story to Instagram and Facebook
Pass both account IDs. Both platforms get the same media.
JSON
If you need different visuals for each (e.g. to tune the crop or overlay), use the per-platform media_urls shape with channel IDs as keys:
JSON
Media requirements
| Platform | Image | Video |
|---|---|---|
| JPEG or PNG, 9:16 recommended | MP4, up to 60 seconds, max 300 MB | |
| JPEG or PNG, 9:16 recommended | MP4, up to 60 seconds |
Stories on both platforms prefer a 9:16 vertical aspect ratio (e.g. 1080 × 1920). Images outside 9:16 are still accepted but are center-cropped or letterboxed by the platform.
Carousels in stories
There is no swipeable carousel inside one story. Several media items become several consecutive stories (see Multi-slide stories above). That is how the native apps behave too.
Scheduling stories
Stories are schedulable the same way as feed posts. Add schedule_at (ISO 8601 UTC) and OmniSocials publishes the story at the scheduled time.
JSON
Because stories only live for 24 hours, scheduling them for a specific moment (e.g. "go live when my campaign starts") is usually more useful than the fire-and-forget pattern of feed posts.
What happens after 24 hours
OmniSocials does not delete the story record from your workspace after the 24 hour window closes. The post still appears in GET /posts with status: "published". The published_urls field still points at the now-expired story on the platform. Clicking the URL after 24 hours typically returns a 404 or redirects to the account's profile.
If you want to archive a story (save it permanently to your profile's Highlights or similar), do that in the native app. OmniSocials does not currently expose a "highlight" action through the API.
Limitations
- A story has no swipeable carousel. Several media items publish as consecutive stories (max 10).
- The
contentfield is not rendered on the story itself. Any text you want visible must be baked into the media. - Stories cannot be updated after publishing. To change a story, delete and recreate. Deleting a Facebook story removes every slide; Instagram stories must be deleted in the Instagram app.
first_commentis ignored on stories (platforms do not support comments on stories), and a hashtag set withhashtag_placement: "first_comment"falls back to the caption.type: "story"is rejected on platforms that do not support stories (all platforms except Instagram and Facebook today). Mixing story-capable and non-story-capable channels in the sameaccountsarray returns400.- Snapchat Spotlight and Stories are on the roadmap, not shipped yet
Related reading
- Creating Posts for the full field reference
- Cross-Posting for the one-request-many-platforms model
- Platforms for per-platform media specs