Social Fetch
Start for freeStart free
Instagram hub

Instagram Stories API

List a profile's live stories as the shared media object — media URLs, timestamps, expiry, link stickers and mentions — for a handle, a profile URL or a user id.

GET /v2/instagram/profiles/{profile}/stories

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v2/instagram/profiles/{profile}/stories lists the stories a public account has live right now (posted in the last 24 hours). It takes a handle (with or without @), a profile URL or a numeric user id. Read data.lookupStatus (found, private or not_found), then data.media. Each story is the media object every v2 list returns, with kind: story, and its extras under story: expiresAt, linkStickers and mentions. Every field is always present and null when Instagram doesn't say; some fields can be null on a profile's first lookup and filled on later ones. meta.version is v2.

Stories come back oldest first, in one response: data.page.hasMore is always false. An account with nothing live is found with an empty data.media. For saved stories use GET /v2/instagram/profiles/{profile}/highlights. Bill from meta.creditsCharged.

Instagram Stories API FAQ

How do I get an Instagram account's stories with the v2 API?

Call GET /v2/instagram/profiles/{profile}/stories with your Social Fetch API key (x-api-key) and a handle, profile URL or numeric user id in the path. Read data.lookupStatus, then data.media.

How much does the Instagram Stories API cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

How long do the stories stay available?

Instagram stories expire 24 hours after they are posted, so this route only returns stories that are live at the moment of the call. createdAt says when each was posted and story.expiresAt when it expires. To keep a story, store its media on your side. Saved stories live in highlights: GET /v2/instagram/profiles/{profile}/highlights.

What does an empty media list mean?

found with an empty data.media means the account exists and has no live story right now. Branch on data.lookupStatus first: private means the account is private and its stories aren't public, and not_found means the profile could not be resolved.

What is in each story?

The shared media object: id, kind: story, mediaType (image or video), createdAt, the account that posted it as owner, image, thumbnail and video URLs, duration and size. Under story: expiresAt, linkStickers (url and the text shown) and mentions (the accounts @mentioned, as profile summaries). Stories have no shortcode, URL or public counts, so those are null. Media URLs are Instagram's and expire after a while.

Other Instagram endpoints