# Instagram Story Downloader (`solid-scraper/instagram-story-downloader`) Actor

📲 Instagram Story Downloader—save stories in seconds with fast, reliable downloads. ✨ Quick, simple, and perfect for creators & fans who don’t want to miss anything. 🚀 Download now and enjoy every moment! 💾

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

## Pricing

from $1.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 Downloader 📥

**Instagram Story Downloader** is a purpose-built actor that helps you extract Instagram story media URLs (videos and images) from publicly available sources. Whether you’re using an instagram story downloader for influencer research, brand monitoring, or building an outreach list, this tool automates the workflow so you can download instagram stories data at scale—saving you hours of manual work.

***

### Why choose Instagram Story Downloader?

| Feature | Benefit |
|---|---|
| ✅ **Instagram story extraction in one run** | Collects story links (video and image) for each Instagram username or profile URL you provide |
| ✅ **Proxy resilience with fallback** | Uses your proxy settings, and falls back to residential proxies if the selected proxy is rejected |
| ✅ **Built-in retries for resilience** | Includes retries with exponential backoff to improve consistency across requests |
| ✅ **Structured dataset output** | Saves results per input to a dataset with `username`, `stories_count`, and a `stories` array |
| ✅ **Batch processing support** | Handles multiple start URLs/usernames in a single actor run |
| ✅ **Automatic URL handling** | Accepts both full Instagram profile URLs and plain usernames, then normalizes internally |

***

### Key features

- 🌐 **Username or profile URL support**: Accepts Instagram profile URLs or plain usernames for an `instagram story download` style workflow
- 🧾 **Structured story results**: Returns a clean `stories` array with `mediatype` (video/image) and `story` URL
- 🎞️ **Video + photo capture**: Includes `mediatype: "video"` items (with `thumbnail`) and `mediatype: "image"` items
- 🛡️ **Proxy support with fallback**: If Instagram rejects the selected proxy, a residential proxy is used as a fallback
- 🔄 **Retries and fallbacks**: Uses retry logic (up to 3 attempts) and waits between attempts to improve success rates
- 💾 **Streaming-like dataset saving**: Pushes each user’s result to the dataset immediately during processing
- 🧠 **Validation for usable story links**: Filters stories so the output focuses on valid-looking Instagram media URLs

***

### Input

Provide input via an `input.json` file. Example structure:

```json
{
  "startUrls": [
    { "url": "https://www.instagram.com/neymarjr/" },
    { "url": "instagram.com/leomessi" },
    { "url": "kyliejenner" }
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

#### Input Fields

| Field | Required | Description |
|---|---|---|
| `startUrls` | ✅ Yes | A list of Instagram profile URLs (for example, `https://www.instagram.com/username`) or plain usernames (for example, `username`). |
| `proxyConfiguration` | ❌ No | Proxy settings for the scraper. If the selected proxy is rejected by Instagram, a residential proxy will be used as a fallback. |
| `proxyConfiguration • proxy support` | ❌ No | When `true`, enables using Apify Proxy for the run (default is prefilled to `true`). |

***

### Output

The actor saves each scraped profile’s data in JSON format into the **Instagram Story Data** dataset.

Sample output object (one input item):

```json
{
  "username": "neymarjr",
  "stories_count": 2,
  "stories": [
    {
      "mediatype": "video",
      "story": "https://example.com/story-video.mp4",
      "thumbnail": "https://example.com/story-thumbnail.jpg"
    },
    {
      "mediatype": "image",
      "story": "https://example.com/story-photo.jpg"
    }
  ]
}
```

Error result shape (when processing fails):

```json
{
  "input": "instagram.com/whatever",
  "error": "Unexpected processing error: ...",
  "stories_count": 0,
  "stories": []
}
```

#### Output Fields

| Field | Type | Description |
|---|---|---|
| `username` | string | The Instagram username derived from the input URL or provided username |
| `stories_count` | number | Number of validated stories found for this user |
| `stories` | array | List of story items for this user (video/image) |
| `stories[] • mediatype` | string | Media type of the story: `"video"` or `"image"` |
| `stories[] • story` | string | The story media URL (video MP4 URL or image URL) |
| `stories[] • thumbnail` | string | Thumbnail URL for video stories (present for `mediatype: "video"`) |
| `input` | string | The original input value used when an error occurs |
| `error` | string | Error message when processing fails (present in error results only) |

***

### How to use Instagram Story Downloader (via Apify Console)

1. **Open Apify Console**\
   Log in at https://console.apify.com and open the **Actors** page.

2. **Find Instagram Story Downloader**\
   Search for **Instagram Story Downloader** in the marketplace and open the actor details.

3. **Go to the INPUT section**\
   Use the built-in form to fill in `startUrls`. You can paste full profile links like `https://www.instagram.com/username/` or plain usernames like `username`.

4. **(Optional) Configure proxy settings**\
   If you enable **Proxy configuration**, set `proxyConfiguration.proxy support` (prefilled to `true`). The actor will apply fallback behavior if the selected proxy is rejected.

5. **Run the actor**\
   Click **Run**. The actor processes each item in `startUrls`, and pushes results to the dataset as it goes.

6. **Watch the logs**\
   Check the live logs for processing progress and any retries/fallbacks while generating your `instagram story download` outputs.

7. **Open the dataset**\
   After the run completes, go to the **OUTPUT** tab and open the **Instagram Story Data** dataset to view scraped stories.

8. **Export to your workflow**\
   Export your dataset as **JSON/CSV** (via the dataset UI) for analysis, research, or automation pipelines.

No coding required—get accurate results in minutes.

***

### Advanced features & SEO optimization

- 🔎 **Built for “instagram story downloader” workflows**: Designed to help with “view and download instagram stories” use cases by outputting story URLs in a structured format
- 🔄 **Validation-first output**: Ensures the `stories` list is populated with usable Instagram media links before returning results, improving the quality of your instagram story saver exports
- 🌐 **Robust public-data scraping**: Scrapes data from publicly available sources and includes retries and fallbacks for resilience
- 🧹 **Cleans story URLs for better downstream use**: Outputs story links suitable for downstream handling (including thumbnails for video stories), aligning with needs like instagram story video downloader and instagram story mp4 downloader workflows

***

### Best use cases

- 📈 **Marketing teams building creator lists**: Quickly gather story media links for targeted competitor or creator research (great for “download instagram stories” projects)
- 🧠 **Researchers doing social media analysis**: Store story counts and media URLs per profile to support structured datasets for analysis
- 🎯 **Influencer outreach ops**: Use story availability and media types to prioritize which creators to contact for campaigns
- 💼 **Brand monitoring**: Track story presence and capture story video/photo URLs across many accounts without manual browsing
- 🧾 **Content archiving & QA**: Keep organized records of instagram highlight downloader and story assets metadata (where available via outputs)
- 💻 **Data pipeline integration**: Feed story URLs into your own systems for media processing or reporting, using the dataset output
- 🖼️ **Asset collection teams**: Use the output to separate `mediatype: "video"` vs `mediatype: "image"` for targeted handling (instagram story photo and instagram story video downloader use cases)

***

### Technical specifications

- **Supported Input Formats**
  - ✅ `startUrls` as an array of Instagram profile URLs or plain usernames
- **Proxy Support**
  - ✅ Proxy configuration via `proxyConfiguration`
  - ✅ Residential fallback if the selected proxy is rejected by Instagram
- **Retry Mechanism**
  - ✅ Retries enabled (up to **3** attempts) with exponential backoff behavior
- **Dataset Structure**
  - ✅ Dataset: **Instagram Story Data** (table view includes `username`, `stories_count`, and `stories`)
- **Rate Limits & Performance**
  - ✅ Includes delays between processing items (via a small delay between requests)
- **Limitations**
  - ❌ If stories cannot be fetched/validated reliably, `stories_count` may be `0` and `stories` may be an empty array
  - ❌ Private/restricted content is not guaranteed to be accessible because results depend on publicly available data

***

### FAQ

#### Can I use Instagram Story Downloader with usernames, not only profile URLs?

✅ Yes. The `startUrls` input accepts both Instagram profile URLs (like `https://www.instagram.com/username`) and plain usernames (like `username`), and the actor derives `username` internally.

#### What does Instagram Story Downloader return for each account?

✅ It returns `username`, `stories_count`, and a `stories` array. Each story item includes `mediatype` (`video` or `image`) and a `story` URL; video items also include a `thumbnail`.

#### Does it support “instagram story download” for multiple accounts in one run?

✅ Yes. You can provide multiple entries in `startUrls`, and each account’s result is pushed to the dataset as processing proceeds.

#### How does the actor handle blocked requests?

✅ It supports proxy resilience. If the selected proxy is rejected by Instagram, it uses a residential proxy fallback and relies on retries with exponential backoff to improve reliability.

#### Is there an error output when something fails?

✅ Yes. When processing fails, the actor pushes an error result containing `input`, `error`, `stories_count: 0`, and `stories: []`.

#### Do I need to write code to run this actor?

✅ No. You can configure the input in Apify Console and run it from the UI, then export the dataset results.

#### What data types are included in the results?

✅ The output focuses on story media URLs and metadata: video stories (`mediatype: "video"` with `story` and `thumbnail`) and image stories (`mediatype: "image"` with `story`).

#### Is this actor meant for legal or compliance-sensitive use?

✅ The actor operates on **publicly available sources**, but you’re responsible for ensuring your use complies with applicable laws and platform rules, including privacy and spam regulations.

***

### Support & feature requests

If you’re using **Instagram Story Downloader** and want improvements, we’d love to hear from you. 💬

- 💡 **Feature Requests**: Share ideas like additional export formats, richer story metadata fields, or enhancements that better support instagram story downloader and instagram story saver workflows.
- 📧 **Contact**: For questions or feedback, email us at <dataforleads@gmail.com>.

Your feedback helps shape the roadmap for this Instagram story downloader actor.

***

### Closing CTA / Final thoughts

*If you’re looking for the most comprehensive way to automate an Instagram Story Downloader workflow, this actor gives you structured outputs you can use right away.*\
*Get your instagram story download data faster with reliable retries, proxy fallback, and dataset-ready results.*

***

### Disclaimer

This tool accesses **publicly accessible sources**. It does not access private profiles, authenticated data, or password-protected pages.

You are responsible for ensuring your use complies with applicable laws (including GDPR/CCPA where relevant), spam regulations, and Instagram/platform terms of service. For data removal requests, contact <dataforleads@gmail.com>.

Use **Instagram Story Downloader** responsibly, ethically, and for legitimate purposes only.

# Actor input Schema

## `startUrls` (type: `array`):

Enter one or more Instagram profile URLs (e.g., https://www.instagram.com/username) or just usernames (e.g., username).

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

Select proxies to be used by the scraper. If the selected proxy is rejected by Instagram, a residential proxy will be used as a fallback.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.instagram.com/neymarjr/"
    }
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {
    "startUrls": [
        {
            "url": "https://www.instagram.com/neymarjr/"
        }
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("solid-scraper/instagram-story-downloader").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 = {
    "startUrls": [{ "url": "https://www.instagram.com/neymarjr/" }],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("solid-scraper/instagram-story-downloader").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 '{
  "startUrls": [
    {
      "url": "https://www.instagram.com/neymarjr/"
    }
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call solid-scraper/instagram-story-downloader --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/71VVcrAEbOCDIbkJf/builds/YdUM63nO2psoEM1Hx/openapi.json