# GET /v1/user/stories: Instagram stories API

The stories an account has up right now, with the media link, time and duration of each. Empty when it has none.

- Call: `GET https://storiesfly.com/api/v1/user/stories`
- Price **1 request**
- Answers up to **3 minutes** old

## Parameters

All parameters go in the query string.

| Name | Type | Sent | Description |
| --- | --- | --- | --- |
| `username` | string | one of | Instagram username. A leading @ is ignored. Send exactly one of username or id. |
| `id` | string | one of | Numeric Instagram id of the account. Send exactly one of username or id. |

## Example request

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"
```

### JavaScript

```javascript
const res = await fetch(
  "https://storiesfly.com/api/v1/user/stories?username=brooklynandbailey",
  { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } }
);
const data = await res.json();
```

### Python

```python
import os
import requests

r = requests.get(
    "https://storiesfly.com/api/v1/user/stories",
    params={"username": "brooklynandbailey"},
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()
```

## Example response

200 OK · X-Units-Charged: 1

```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
    }
  ]
}
```

A real answer, shortened: lists are cut to two items and long texts to 160 characters.

## Price and freshness

A call takes 1 request. Free requests are spent first, then your balance. The [pricing](https://storiesfly.com/developers/pricing) page has the rates.

Answers are kept for up to 3 minutes. Asking again inside that time returns the same answer and takes 1 request again.

## Errors

A failed call answers with an HTTP status and a body `{error, code}`. These are the codes this endpoint gives. [Errors and what is charged](https://storiesfly.com/developers/docs#errors) covers all of them.

| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | A parameter is missing or wrong, or not exactly one of `username` or `id` was sent. `fields` lists the names. Free. |
| `401` | `unauthorized` | The `X-Api-Key` header is missing or the key is wrong. Free. |
| `402` | `credits_exhausted` | The free requests and the balance are used up. Top up in the [dashboard](https://storiesfly.com/developers/dashboard). Free. |
| `403` | `telegram_required` | The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free. |
| `403` | `private_account` | The account is private. Charged like an answer. |
| `404` | `not_found` | The account does not exist. Charged like an answer. |
| `429` | `rate_limited` | More requests in a second than your level allows. Wait for the `Retry-After` header. Free. |
| `500` | `internal_error` | A fault on our side. Retry shortly. Refunded. |
| `503` | `upstream_unavailable` | Our side failed or timed out. Retry shortly. Refunded. |

## Questions about this endpoint

### What if the account has no stories?

`stories` is an empty list and the call still takes 1 request. An empty list is an answer like any other.

### How long is a story available?

Instagram keeps a story up for 24 hours. After that it is gone from this list. Save the media file if you need it later.

### How old can an answer be?

Up to 3 minutes. A story posted a minute ago may not be in the list yet.

## Related endpoints

- [GET /v1/user/highlights](https://storiesfly.com/developers/docs/user-highlights): Highlight covers and titles
- [GET /v1/story](https://storiesfly.com/developers/docs/story): One story by link or id
- [GET /v1/highlight](https://storiesfly.com/developers/docs/highlight): Every story in a highlight, by link or id
- [GET /v1/user/profile](https://storiesfly.com/developers/docs/user-profile): Profile with verified badge, bio, link and counts

## Links

- [This page on the site](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