Instagram Stories
Instagram Stories are photos and videos an account shares for 24 hours, often carrying a link sticker, a tagged account, or a time-limited offer that never reaches the main feed. Saving them while they are live gives brand, marketing, and research teams a record of launches, promotions, and creator activity that would otherwise disappear.
Instagram Stories API Features
- Everything the account has liveOne username returns all of the stories the account has up at the moment you send the request.
- Media ready to archiveEach story comes with its image or video URL, width and height, and a cover image, so the content can be stored or reviewed later.
- When it went up and when it comes downThe posting time arrives as published_at and the expiry time as extra.expires_at, which tells you exactly how long you have before the next collection.
- Links and mentions stay with the storyLink sticker destinations are listed in extra.link_urls and tagged accounts in extra.mentions, attached to the story that carried them.
Instagram Stories API Parameters
| Parameters | Required | Description |
|---|---|---|
username | Required | Username of the public Instagram account whose current stories you want. The leading @ is optional. |
How to Use the Instagram Stories API
Send a username to the Instagram Stories API, wait for the task to finish, and read the stories from the task result.
- Pick the public account you want to check, for example natgeo.
- POST {"username": "natgeo"} to /v1/instagram/stories and keep the task_id from the response.
- Call GET /v1/tasks/{task_id} every few seconds until status is succeeded.
- Read the stories in results.items; when results.has_more is true, pass results.next_cursor to get the next page.
curl -X POST "https://api.socq.ai/v1/instagram/stories" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"natgeo"}'
# The response contains a task_id.
# GET /v1/tasks/{task_id} returns the stories once status is succeeded.Instagram Stories API Use Cases
- Daily story archive: Collect a brand's stories through the Instagram Stories API once or twice a day and keep the media and posting times, so every story stays reviewable after it expires.
- Promotion tracking: Follow the link sticker URLs competitors add to their stories to see which products, sales, and landing pages they are pushing this week.
- Creator campaign checks: Match a creator's story time, media, and link sticker against the brief to confirm the agreed story went live.
Instagram Stories API Pro Tips
- Schedule Instagram Stories API runs less than 24 hours apart so every story is captured at least once while it is live.
- Download the images and videos you want to keep soon after collection, because story media links are temporary CDN addresses.
- When you collect the same account again, use the story id to skip stories you have already stored.
- For stories an account keeps on its profile, use Instagram Story Highlights and Instagram Highlight Items.
Related APIs
Beyond the Instagram Stories API, use these APIs when you need a different type of public Instagram data.
- Instagram Posts API — Collect public posts, media, hashtags, mentions, timestamps, and engagement by username.
- Instagram Reels API — Collect public Reels, media, audio, hashtags, mentions, and engagement by username.
- Instagram Profiles API — Retrieve public profile identity, biographies, links, account flags, categories, and visible counts by username.
- Instagram Tagged Posts API — Collect public posts that tag selected profiles with authors, media, mentions, tagged-user context, and engagement.
- Instagram Story Highlights API — List public Story Highlight containers by username with titles, owner context, media counts, and reusable highlight IDs.
- Instagram Similar Accounts API — List the accounts Instagram suggests as similar to a username, with usernames, names, avatars, and verification status.
- Instagram Followers Count API
- Instagram Search API
- Instagram Comments API
- Instagram Followers List API
- Instagram Following List API
- Instagram Hashtag Posts API
- Instagram Transcript API
- Instagram Audio Reels API
- Instagram Highlight Items API
- Instagram Post Info API
- Instagram Reels Search API
- Instagram Trending Reels API
- Instagram Comment Replies API
- Instagram Post Likers API
- Instagram Location Info API
- Instagram Location Posts API
- Instagram Location Search API
- Instagram Hashtag Search API
- Instagram Account Age Checker API