# Instagram Stories API (https://www.socialcrawl.dev/platforms/instagram/stories)

> Returns the active stories currently in a user's story tray. Each story includes its id, media URLs (image or video), thumbnail, duration, capture time, and the author. Pass either `handle` or `user_id`. Passing `user_id` is faster because no username lookup is needed. A user with no active stories returns an empty list — not an error.

TL;DR: `GET /v1/instagram/stories` costs 5 credits per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | no | Instagram username without the @ symbol. |
| `user_id` | no | Instagram numeric user ID. Use this for faster responses. |
| `safe_url` | no | When true, returns URL-safe media links suitable for embedding. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/instagram/stories" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I get a user's active Instagram stories with an API?

Send a GET request to /v1/instagram/stories with either the handle or the user_id parameter. SocialCrawl returns a JSON list of the stories currently in that user's tray, each with media URLs, thumbnail, duration, capture time, and author.

### Should I pass handle or user_id to the stories endpoint?

Both work. Passing user_id is faster because SocialCrawl skips the username lookup step. If you only have the username, pass handle and the account is resolved for you before the stories are fetched.

### What happens if the user has no active stories?

You get an empty list, not an error. Instagram stories expire after 24 hours, so an account with nothing live returns zero items and the call still succeeds normally.

### How much does the Instagram Stories API cost per call?

Each call costs 5 credits on the advanced tier, regardless of how many stories are in the tray. New accounts get 100 free credits with no card, so you can test it right away.

### Can I get CDN-safe media URLs for the stories?

Yes. Add the optional safe_url parameter and the response returns proxied, CDN-safe media URLs that are easier to fetch and store than the raw Instagram links, which helps with story archiving.

See the full Instagram API: https://www.socialcrawl.dev/platforms/instagram

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to fetch a user's active Instagram stories with an API
- Which Instagram API returns story media URLs and expiry time