# Instagram Story Scraper 📸 (`scraper-engine/instagram-story-scraper`) Actor

📸 Instagram Story Scraper extracts public Instagram story data fast & accurately. Automate insights, track trends, and support marketing research with ease. 🚀 Perfect for creators, analysts & brands. ⚡️ Get results in moments!

- **URL**: https://apify.com/scraper-engine/instagram-story-scraper.md
- **Developed by:** [Scraper Engine](https://apify.com/scraper-engine) (community)
- **Categories:** Social media, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 📸 Instagram Story Scraper

Pull **live (24-hour) Instagram stories** for any public profile and get back the **full, structured story payload** — video & image versions, music, stickers, links, mentions, engagement flags, and optional **on-image caption text (OCR)**. Feed it bare usernames, `@handles`, or full profile URLs in bulk and watch results stream into your dataset in real time.

***

### ✨ Why Choose This Actor?

- 🧱 **Complete data** — nothing stripped. Every field Instagram returns for a story is preserved, in a clean canonical order.
- 👤 **Any input format** — `natgeo`, `@kyliejenner`, `instagram.com/taylorswift`, or `https://www.instagram.com/therock/`. Mix and match, in bulk.
- 🛡️ **Self-healing proxy ladder** — starts direct, auto-escalates to datacenter, then a **sticky residential** proxy only when needed. Clear logs at every step.
- 📝 **OCR captions** — optionally reads text burned into the story frame (titles, stickers, mentions) into `extractedCaption`.
- 💾 **Live saving** — each story is pushed the moment it's ready, so a partial run never loses data.
- 🗂️ **Six ready-made table views** — slice results by Media, Images, Music, Stickers, Engagement, or a quick Overview.

***

### 🔑 Key Features

| Feature | Description |
|--------|-------------|
| 📋 Bulk input | Scrape many profiles in one run |
| 🎬 Full media | `video_versions`, `video_dash_manifest`, codecs, qualities, dimensions |
| 🖼️ Image versions | Every cover-frame candidate resolution |
| 🎵 Music | `music_metadata` enriched from story music stickers |
| 🔗 Stickers & links | Link stickers, feed-media stickers, mentions, reshares |
| ⏱️ CDN expiry enrichment | Fills `url_expiration_timestamp_us` from CDN `oe=` when missing |
| 📝 OCR caption | Optional `extractedCaption` per story |

***

### 📥 Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `usernames` | array | ✅ | Usernames or profile URLs (bulk). |
| `sessionId` | string | ✅ | Your Instagram `sessionid` cookie (stories are login-gated). |
| `extractCaptionText` | boolean | ➖ | Enable OCR caption extraction. Default `false`. |
| `proxyConfiguration` | object | ➖ | Proxy settings. Default: direct with auto-fallback. |

#### Example

```json
{
  "usernames": ["therock", "@kyliejenner", "https://www.instagram.com/natgeo/"],
  "sessionId": "REDACTED_SESSIONID_COOKIE",
  "extractCaptionText": false,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

> 🍪 **Where to get `sessionId`:** Log into Instagram in your browser → DevTools → **Application → Cookies → instagram.com → `sessionid`**. Treat it like a password.

***

### 📤 Output

Each dataset item is one story with the full Instagram payload. Abridged example:

```json
{
  "scraped_username": "therock",
  "id": "3920998746292350747_232192182",
  "pk": "3920998746292350747",
  "code": "DZqL5Xdge8b",
  "taken_at": 1781637893,
  "expiring_at": 1781724293,
  "media_type": 2,
  "product_type": "story",
  "video_duration": 60.04,
  "has_audio": true,
  "video_versions": [{ "width": 720, "height": 1280, "url": "https://…" }],
  "image_versions2": { "candidates": [{ "width": 1080, "height": 1920, "url": "https://…" }] },
  "music_metadata": { "music_asset_info": { "audio_asset_id": "18121840837670133" } },
  "story_link_stickers": [{ "story_link": { "url": "https://…" } }],
  "extractedCaption": ""
}
```

#### 🗂️ Dataset views

| View | Shows |
|------|-------|
| 🗂️ Overview | IDs, type, timestamps, duration, OCR caption |
| 🎬 Media & Video | Codecs, qualities, dimensions, video versions |
| 🖼️ Image Versions | All cover-frame candidates |
| 🎵 Music | Music metadata & music stickers |
| 🔗 Stickers, Links & Mentions | Link stickers, feed media, mentions, reshares |
| 💬 Engagement & Flags | Like/reply/reshare/save flags, paid partnership |

***

### 🚀 How to Use (Apify Console)

1. Log in at <https://console.apify.com> → **Actors**.
2. Open **Instagram Story Scraper**.
3. Paste usernames / URLs, add your `sessionId`, choose proxy & OCR options.
4. Click **Start**.
5. Watch the logs stream live story collection.
6. Open the **Output** tab and switch between the six section views.
7. Export to JSON / CSV / XLSX.

***

### 🤖 Use via API

```bash
curl -X POST "https://api.apify.com/v2/acts/<ACTOR_ID>/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "usernames": ["therock", "@kyliejenner"],
        "sessionId": "YOUR_SESSIONID",
        "extractCaptionText": false
      }'
```

***

### 🎯 Best Use Cases

- 📈 Monitor competitor / influencer story activity
- 🗞️ Archive brand & creator stories before they expire
- 🔗 Track link stickers, promos, and product drops
- 🎵 Analyze trending audio usage in stories

***

### 💸 Pricing

This actor uses **pay-per-event**: you're charged per story successfully delivered to your dataset (`story-result`). Profiles with no live stories cost nothing beyond the run start. The optional OCR step runs on Apify compute and is included in the run usage.

***

### ❓ FAQ

**Do I need a session cookie?** Yes — stories are only visible to logged-in viewers, so a valid `sessionid` is required.

**What if a profile has no active stories?** You'll see a friendly "no live stories" log line and no items for that profile — no charge.

**Will I get blocked?** The actor starts direct and only escalates to datacenter then sticky residential proxies when Instagram pushes back, with backoff retries. For heavy use, enable Apify Proxy.

**Why is `pk` sometimes huge?** It's Instagram's numeric primary key, returned as-is.

***

### ⚖️ Legal & Compliance

- Data is collected only from **publicly available** profiles you have the right to view.
- Do not scrape private accounts or content you aren't authorized to access.
- You are responsible for compliance with GDPR, CCPA, Instagram's ToS, and local laws.

***

### 🛟 Support & Feedback

Found a bug or want a new field exposed? Open an issue on the actor's **Issues** tab — real answers, fast.

# Actor input Schema

## `usernames` (type: `array`):

📋 One or more Instagram usernames or profile URLs to pull stories from. Any format works — bare handle (natgeo), @handle (@kyliejenner), or full URL (https://www.instagram.com/therock/). Supports bulk input.

## `sessionId` (type: `string`):

🍪 Your Instagram `sessionid` cookie value. Stories are private to logged-in viewers, so a valid session is required. Get it from your browser DevTools → Application → Cookies → instagram.com → `sessionid`. Keep it secret — treat it like a password.

## `extractCaptionText` (type: `boolean`):

🤖 When enabled, reads visible text burned into each story frame (titles, stickers, mentions) into the `extractedCaption` field using OCR. Adds a little extra processing per story.

## `proxyConfiguration` (type: `object`):

🌐 Proxy settings. By default the actor runs direct (no proxy) and only falls back to a datacenter — then a sticky residential — proxy if Instagram pushes back. Leave off for the smart auto-ladder, or pin a specific group here.

## Actor input object example

```json
{
  "usernames": [
    "therock",
    "@kyliejenner"
  ],
  "extractCaptionText": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "usernames": [
        "zuck",
        "https://www.instagram.com/therock/",
        "instagram.com/taylorswift",
        "@kyliejenner",
        "http://instagram.com/natgeo"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scraper-engine/instagram-story-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "usernames": [
        "zuck",
        "https://www.instagram.com/therock/",
        "instagram.com/taylorswift",
        "@kyliejenner",
        "http://instagram.com/natgeo",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scraper-engine/instagram-story-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "usernames": [
    "zuck",
    "https://www.instagram.com/therock/",
    "instagram.com/taylorswift",
    "@kyliejenner",
    "http://instagram.com/natgeo"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scraper-engine/instagram-story-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scraper-engine/instagram-story-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/gnGJ30p9EI7OEqW52/builds/eWZ7yctX680wXtYok/openapi.json