instagram/
stories

The Instagram Stories API collects the stories a public Instagram account is showing right now from its username, returning each story's image or video, posting and expiry times, and link stickers.

Instagram Stories API

Username input
Live stories
Link stickers
0.5 credits / result
Ready
Ready

Enter parameters and send a request. The task status and normalized results will appear here.

README

By SocQ · Updated

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

ParametersRequiredDescription
usernameRequiredUsername 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.

  1. Pick the public account you want to check, for example natgeo.
  2. POST {"username": "natgeo"} to /v1/instagram/stories and keep the task_id from the response.
  3. Call GET /v1/tasks/{task_id} every few seconds until status is succeeded.
  4. 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.

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.

Explore other platforms

Combine Instagram data with public data from other supported social platforms.

Instagram Stories API — FAQ

Instagram Stories API is a programmatic interface for collecting the stories a public Instagram account currently has live, using its username as input. It returns each story's ID and link, image or video, cover image, author, and posting time.

Yes. Send the username of a public account and its stories come back as data, with no Instagram login needed on your side.

When a story carries a link sticker, the Instagram Stories API returns the sticker's destination URL in extra.link_urls for that story.

Stories stay up for 24 hours, so collecting once or twice a day captures each one while it is live.

The task ends with a message that the profile could not be found, and the credits held for it are returned to your balance.

With the Instagram Stories API you pay 0.5 credits for each story returned, and a request that finds no live stories costs nothing.