Instagram Stories API
Retrieve the stories a public profile currently has live: image and video links, timestamps and expiry times, in the same simple JSON as every other endpoint.
Request
GET /v1/profiles/{username}/stories ·
3 credits per successful call
Paid plans
curl "https://api.igramapi.com/v1/profiles/example_creator/stories" \
-H "Authorization: Bearer YOUR_API_KEY" import requests
response = requests.get(
"https://api.igramapi.com/v1/profiles/example_creator/stories",
headers={"Authorization": "Bearer YOUR_API_KEY"},
timeout=30,
)
response.raise_for_status()
print(response.json()) const response = await fetch("https://api.igramapi.com/v1/profiles/example_creator/stories", {
method: "GET",
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(await response.json()); <?php
$ch = curl_init("https://api.igramapi.com/v1/profiles/example_creator/stories");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_KEY",
],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data); Response
{
"username": "example_creator",
"user_id": "1234567890",
"count": 2,
"items": [
{
"story_id": "3012345678900000001",
"type": "image",
"media_url": "https://scontent.cdninstagram.com/v/example/story1.jpg",
"thumbnail": "https://scontent.cdninstagram.com/v/example/story1.jpg",
"duration": 0,
"taken_at": 1761895000,
"expires_at": 1761981400,
"has_audio": null
},
{
"story_id": "3012345678900000002",
"type": "video",
"media_url": "https://scontent.cdninstagram.com/v/example/story2.mp4",
"thumbnail": "https://scontent.cdninstagram.com/v/example/story2.jpg",
"duration": 8.4,
"taken_at": 1761896500,
"expires_at": 1761982900,
"has_audio": true
}
],
"cached": false
} All values above are made-up examples. Media links are temporary Instagram CDN addresses.
Parameters
| Name | In | Description |
|---|---|---|
usernamerequired | path | Instagram username. |
story_id | query | Return only this story. |
Response fields
| Field | Type | Description |
|---|---|---|
count | integer | Number of active stories. |
items[].story_id | string | Story identifier. |
items[].type | string | image or video. |
items[].media_url / thumbnail | string | Temporary CDN links. |
items[].taken_at / expires_at | integer | null | Unix timestamps. |
items[].duration / has_audio | number / boolean | null | Video details. |
Only what is live
Stories disappear after 24 hours. The response lists exactly what is active now, with the expiry time of each.
Empty is a valid answer
A profile with no active story returns count: 0, not an error, and the call is billed normally.
Filter one story
Pass story_id to fetch a single story you already know about.
Paid plans
Stories use 3 credits per call and are available on every paid plan.
Instagram stories data for monitoring
Brands use the Stories API to keep a record of what creators and competitors post in Stories, which is otherwise gone after a day. Poll a profile on a schedule, store each new story_id, and download the media with the Downloader API while the link is valid.
Because stories expire, run your job at least every few hours for accounts that post often.
Limits to know
Only public accounts are supported. Stories visible only to close friends are not accessible, and results can be briefly cached, so a story posted seconds ago may take a moment to appear.
Frequently asked questions
Is the Stories API on the free plan?
No. Stories, highlights and hashtag feeds need a paid plan. Every other endpoint works on the free plan.
Can I see who viewed a story?
No. Viewer lists are private to the account owner and are never exposed.
Do I need to follow the account?
No. You only need the username of a public account.
What does a profile with no stories return?
HTTP 200 with `count: 0` and an empty `items` list.
Errors cost nothing. Any response with a status of 400 or above is refunded, and every error has the same shape. See error handling and credits and rate limits.
Try the Stories API free
Create a key and make your first request in minutes. 100 free credits every month.