Instagram Stories API
Send a username and get the stories that account has up right now, as JSON: a media link, the time and the video length of each. One request returns all of an account's stories. You do not log in to Instagram. You send your API key.
Three endpoints for stories
user/stories returns every story an account has up. story returns one story, by its link or id. highlight returns a highlight with every story in it.
All three are GET requests under /api/v1/ with the key in the X-Api-Key header.
| Endpoint | You send | You get | Requests | Fresh for |
|---|---|---|---|---|
GET /api/v1/user/stories | username or id of the account | The stories the account has up now | 1 | 3 minutes |
GET /api/v1/story | url or id of the story | One story and its account | 1 | 3 minutes |
GET /api/v1/highlight | url or id of the highlight | The highlight and every story in it | 1 | 15 minutes |
Fields of a story
The answer of user/stories has user (the account's id and username) and stories. stories is an empty list when the account has none up.
Every story has the same fields, in this order.
| Field | Type | Meaning |
|---|---|---|
id | string | Id of the story. Pass it to story as id |
url | string | Link to the story on instagram.com |
taken_at | number | When the story was posted, as Unix time in seconds |
taken_at_iso | string | The same moment as an ISO 8601 date in UTC |
media_type | string | photo or video |
media_url | string | Link to the photo, or to the video file when the story is a video |
thumbnail_url | string | Link to a still image of the story. For a photo it is the photo itself |
video_duration | number or null | Length of a video in seconds. null for a photo |
Example request
This call reads the stories of brooklynandbailey. Put your own key in the header.
curl "https://storiesfly.com/api/v1/user/stories?username=brooklynandbailey" \
-H "X-Api-Key: sf_live_your_key"Example response
The first story is a video with its length in seconds, the second is a photo. The answer carries X-Units-Charged: 1. Long media links are shortened in this example.
{
"user": {
"id": "286628010",
"username": "brooklynandbailey"
},
"stories": [
{
"id": "4008637512964239886",
"url": "https://www.instagram.com/stories/brooklynandbailey/4008637512964239886/",
"taken_at": 1792086850,
"taken_at_iso": "2026-10-15T17:54:10.000Z",
"media_type": "video",
"media_url": "https://scontent-lga3-2.cdninstagram.com/o1/v/t2/f2/m78/AQPH74NahzbMjNpeMfSF0lL2HOrUTana5q4EzP0NQZQHGeUJCeTuDuAvmgXOQa7K9UWTibUM1hngLk3u7IsLT4iSQQxNyL_rn0rbjwk…",
"thumbnail_url": "https://scontent-lga3-3.cdninstagram.com/v/t51.71878-15/851828943_1070743629289559_5712408482754146592_n.jpg",
"video_duration": 7.666
},
{
"id": "4008666677715020807",
"url": "https://www.instagram.com/stories/brooklynandbailey/4008666677715020807/",
"taken_at": 1792090327,
"taken_at_iso": "2026-10-15T18:52:07.000Z",
"media_type": "photo",
"media_url": "https://scontent-lga3-1.cdninstagram.com/v/t51.82787-15/850290260_18648501079036011_4776426096727558547_n.jpg",
"thumbnail_url": "https://scontent-lga3-1.cdninstagram.com/v/t51.82787-15/850290260_18648501079036011_4776426096727558547_n.jpg",
"video_duration": null
}
]
}Highlights
highlight takes the link of a highlight or its id and returns id, title, cover_url, items_count, created_at, created_at_iso, user and stories. The stories in it have the fields above.
The whole highlight is 1 request, however many stories it holds.
To find the ids of an account's highlights, call user/highlights. For each highlight it returns id, title, cover_url, items_count, created_at and created_at_iso, a page at a time with next_cursor, and a page takes 1 request.
What it costs
An account's stories take 1 request, however many stories it has. Reading the stories of 1,000 accounts takes 1,000 requests, which is $1.50 at the Start rate.
An account with no stories up returns an empty list and is charged like any other answer. A wrong parameter and a failure on our side cost nothing.
You get 100 free requests when you sign in with Telegram. See pricing for the levels and the billing rules.
How fresh the data is
Answers of user/stories and story are at most 3 minutes old. Answers of highlight are at most 15 minutes old.
Instagram keeps a story up for 24 hours. After that user/stories no longer lists it, and story answers not_found, which is charged like an answer.
Media links point to Instagram's servers and stop working after some time. Save the file when you need it later.
What it cannot do
- It reads public accounts only. For a private account
user/storiesanswersprivate_account(HTTP 403), which is charged like an answer. - You never log in to Instagram, and your own account never appears among the story's viewers.
- It cannot post, reply or send messages, and it does not show who viewed a story.
Reference and next steps
Every parameter, error and example is in the docs: user/stories, story, highlight and user/highlights.
Get your key to make the first call. To see how this differs from Instagram's official API, read Instagram API without login. Rates are on the pricing page.
Questions developers ask
How many requests does it take to get all the stories of an account?
One. user/stories returns every story the account has up in a single call, and a call takes 1 request.
How fresh are the stories?
At most 3 minutes old. A highlight is at most 15 minutes old.
Can I get the stories of a private account?
No. user/stories answers private_account for a private account. The profile of that account still works.
Will my own Instagram account show up among the viewers of a story?
You never log in to Instagram, and your own account never appears among the story's viewers.
How long do the media links work, and how do I keep a story?
The links point to Instagram's servers and expire after some time. Download the file from media_url when you get the answer and store it yourself. A story is up for 24 hours, so a story you did not save cannot be fetched later.
Your first 100 requests are on us
Sign in with Telegram, create a key, call any endpoint. Top up only when you need more.