> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/instagram/v2-instagram-profiles-profile-stories>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/instagram/v2-instagram-profiles-profile-stories.mdx>

---

# 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` 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`.

## Request

- **Endpoint:** `GET /v2/instagram/profiles/{profile}/stories`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by handle or user id
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v2/instagram/profiles/profile/stories/get)
- **Platform page:** [/platforms/instagram](https://www.socialfetch.dev/platforms/instagram)

## 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.