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

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

**Response**

```json
{
  "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](https://storiesfly.com/developers/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/stories` answers `private_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](https://storiesfly.com/developers/docs/user-stories), [story](https://storiesfly.com/developers/docs/story), [highlight](https://storiesfly.com/developers/docs/highlight) and [user/highlights](https://storiesfly.com/developers/docs/user-highlights).

[Get your key](https://storiesfly.com/developers/dashboard) to make the first call. To see how this differs from Instagram's official API, read [Instagram API without login](https://storiesfly.com/developers/instagram-api-without-login). Rates are on the [pricing page](https://storiesfly.com/developers/pricing).

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

## Links

- [This page on the site](https://storiesfly.com/developers/instagram-stories-api)
- [Read the stories docs](https://storiesfly.com/developers/docs/user-stories)
- [Instagram data API](https://storiesfly.com/developers): what the API is and what it returns
- [Pricing](https://storiesfly.com/developers/pricing): rates, examples and billing rules
- [Documentation](https://storiesfly.com/developers/docs): quick start, authentication, errors and every endpoint
- [OpenAPI file](https://storiesfly.com/openapi.json): the whole API in one file
- [API dashboard](https://storiesfly.com/developers/dashboard): get a key and top up
- [Changelog](https://storiesfly.com/developers/changelog): what changed and when