# 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 public account with no active stories returns an empty list at no charge, not an error; a private account returns 404. Stories carry no public caption and no public like, comment, or view count: Instagram shows story engagement only to the account owner, and it is never fabricated here.

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 | Optional and usually ignored: most responses carry ordinary media URLs whether or not you send it. Same price either way. |
| `since` | no | Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. |
| `until` | no | Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/instagram/stories" \
  --data-urlencode "handle=instagram" \
  -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