# List Instagram stories

> List an Instagram account's live stories, with when each expires.

Canonical: <https://www.tryadeli.com/docs/api/posts/list-instagram-stories>

`GET https://app.tryadeli.com/api/v1/posts/instagram/stories`

Authorization: `Bearer <API key>` — see [Authentication](https://www.tryadeli.com/docs/authentication)

List an Instagram account's active stories: everything it posted in the last
24 hours, newest first. Use it to let someone pick a story, for example to run
an automation only on replies to that story: the story's `id` is the `story.id`
on its replies, and passing it as `storyId` to
[List messages](https://www.tryadeli.com/docs/api/messages/list-messages) returns everyone who replied.

The list comes live from Instagram on every call, so a story posted a moment
ago shows up straight away, and one that has expired is gone.

**Query parameters**

| Name        | Type   | Required | Description                                                                       |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------- |
| `accountId` | `uuid` | Yes      | The connected Instagram account.                                                  |
| `profileId` | `uuid` |          | Optional, because accountId names its profile. If you pass both, they must agree. |

Each story has:

**Story fields**

| Name               | Type             | Required | Description                                                                          |
| ------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------ |
| `id`               | `string`         |          | The story's Instagram media id.                                                      |
| `mediaType`        | `string \| null` |          | IMAGE or VIDEO.                                                                      |
| `mediaProductType` | `string`         |          | Always STORY.                                                                        |
| `mediaUrl`         | `string \| null` |          | The image or video. Null for a video with licensed music; show thumbnailUrl instead. |
| `thumbnailUrl`     | `string \| null` |          | A video story's cover image. Null for images.                                        |
| `permalink`        | `string \| null` |          | The story on Instagram. It opens only while the story is live.                       |
| `timestamp`        | `date-time`      |          | When the story was posted.                                                           |
| `expiresAt`        | `date-time`      |          | When the story stops being live, 24 hours after timestamp.                           |

> **Note: Only live stories**
>
> Instagram keeps a story for 24 hours, and so does this list. Media URLs stop
> working when the story expires, so copy anything you want to keep. Live
> video broadcasts and stories reshared from other accounts are never
> included.

The account needs the basic read permission that every Instagram connection
has. An account with no live stories returns `"stories": []`.

**Errors** — `401 unauthorized`, `400 invalid_request`, `404 profile_not_found`,
`404 account_not_found`, `403 permission_required` with missing permission and
reconnect details, `422 connection_expired`, `502 provider_error`.

## Request examples

**cURL**

```bash
curl "https://app.tryadeli.com/api/v1/posts/instagram/stories?accountId=00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/posts/instagram/stories?accountId=00000000-0000-0000-0000-000000000000", {
  headers: {
    Authorization: `Bearer ${process.env.ADELI_API_KEY}`,
  },
});
console.log(await response.json());
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://app.tryadeli.com/api/v1/posts/instagram/stories",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "accountId": "00000000-0000-0000-0000-000000000000",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "platform": "instagram",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "stories": [
    {
      "id": "17900000000000003",
      "mediaType": "VIDEO",
      "mediaProductType": "STORY",
      "mediaUrl": null,
      "thumbnailUrl": "https://scontent.cdninstagram.com/v/story-cover.jpg",
      "permalink": "https://instagram.com/stories/acmecoffee/3480000000000000003",
      "timestamp": "2026-11-10T15:20:00.000Z",
      "expiresAt": "2026-11-11T15:20:00.000Z"
    },
    {
      "id": "17900000000000002",
      "mediaType": "IMAGE",
      "mediaProductType": "STORY",
      "mediaUrl": "https://scontent.cdninstagram.com/v/story.jpg",
      "thumbnailUrl": null,
      "permalink": "https://instagram.com/stories/acmecoffee/3480000000000000002",
      "timestamp": "2026-11-10T09:05:00.000Z",
      "expiresAt": "2026-11-11T09:05:00.000Z"
    }
  ]
}
```

### 404

```json
{
  "error": {
    "code": "account_not_found",
    "message": "Instagram account not found"
  }
}
```
