# Instagram Media Downloader (`spider_studio/instagram-media-download`) Actor

Download validated Instagram and Facebook CDN media into the run's key-value store and return file metadata.

- **URL**: https://apify.com/spider\_studio/instagram-media-download.md
- **Developed by:** [NewLai](https://apify.com/spider_studio) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 instagram url processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

### What does Instagram Media URL Extractor API do?

Instagram Media URL Extractor API resolves public Instagram post IDs, post URLs, reel URLs, TV URLs, and share links into direct image and video CDN URLs. Each Dataset row contains the canonical post shortcode, resolved Instagram page, media type, ordered assets, dimensions, and convenient `imageUrls` and `videoUrls` arrays.

No Instagram login or session cookie is required. The Actor returns URLs only and does not download or store the binary media files, making it suitable for API integrations, downstream download pipelines, content analysis, and automation on Apify.

### Why use an Instagram media URL extractor?

- Turn a copied Instagram share link into direct media URLs.
- Resolve images, videos, reels, and mixed carousel posts.
- Submit up to 100 post references in one run.
- Receive normalized JSON suitable for downloaders and media-processing pipelines.
- Follow Instagram redirects safely while rejecting arbitrary external targets.

### How to extract Instagram image and video URLs

1. Copy an Instagram post ID/shortcode or public share link.
2. Add one or more values to `postIdsOrUrls` in the Actor's **Input** tab.
3. Keep the default residential proxy setting: requests start in GB and switch to DE after the first failed attempt.
4. Click **Start** and open the Dataset output.
5. Use `assets`, `imageUrls`, or `videoUrls` in your downstream workflow.

### Input

`postIdsOrUrls` accepts Instagram shortcodes such as `ABC123example`, canonical `/p/` links, `/reel/` links, `/tv/` links, profile-prefixed links such as `/{username}/reel/{shortcode}/`, and Instagram `/share/` links. URLs must use HTTPS and an official Instagram hostname. Redirect destinations are validated on every hop.

```json
{
  "postIdsOrUrls": [
    "ABC123example",
    "https://www.instagram.com/reel/XYZ987example/?igsh=example"
  ],
  "maxConcurrency": 5
}
```

### Output

You can download the Dataset in various formats such as JSON, HTML, CSV, or Excel. Direct CDN URLs are temporary and should be consumed promptly.

```json
{
  "success": true,
  "position": 1,
  "input": "ABC123example",
  "resolvedUrl": "https://www.instagram.com/p/ABC123example/",
  "postCode": "ABC123example",
  "postUrl": "https://www.instagram.com/p/ABC123example/",
  "mediaType": "carousel",
  "imageUrls": ["https://scontent.cdninstagram.com/example-image.jpg"],
  "videoUrls": ["https://scontent.cdninstagram.com/example-video.mp4"],
  "assets": [
    {"position": 1, "type": "image", "url": "https://scontent.cdninstagram.com/example-image.jpg", "width": 1080, "height": 1350},
    {"position": 2, "type": "video", "url": "https://scontent.cdninstagram.com/example-video.mp4", "width": 1080, "height": 1920}
  ],
  "error": null
}
```

### What Instagram media URL data is returned?

| Field | Type | Description |
| --- | --- | --- |
| `input`, `position` | string, integer | Original reference and its input order. |
| `resolvedUrl` | string | Final validated Instagram page after redirects. |
| `postCode`, `postUrl` | string | Resolved shortcode and canonical post URL. |
| `mediaType` | string | `image`, `video`, or `carousel`. |
| `imageUrls`, `videoUrls` | arrays | Direct URLs grouped by media type. |
| `assets` | array | Ordered URLs, media types, widths, and heights. |
| `success`, `error` | mixed | Per-input result status and diagnostics. |

### How much does it cost to extract Instagram media URLs?

This Actor uses pay-per-event pricing with platform usage included. At the default 512 MB memory, the Actor start event costs $0.002. Only successfully resolved Instagram references trigger a `url-processed` event. Error rows remain visible in the Dataset for diagnostics but are not charged. Carousel posts still count as one successful result regardless of asset count.

| Apify discount tier | Price per successful result | Price per 1,000 successful results |
| --- | ---: | ---: |
| Free | $0.0030 | $3.00 |
| Bronze | $0.0025 | $2.50 |
| Silver | $0.0022 | $2.20 |
| Gold, Platinum, Diamond | $0.0020 | $2.00 |

One or more Instagram requests may be needed for each input because share URLs can redirect. Transient failures are limited to two retries (three total attempts). With the default proxy setting, the first attempt uses GB; after a failure the run switches to DE and keeps DE active. A user-selected non-GB country or custom proxy URL is respected and does not trigger the automatic fallback. Set a maximum charge per run in Apify when you need a hard spending limit.

### Tips and limitations

Only public posts are supported. Private, deleted, age-gated, region-restricted, or login-gated posts may fail. Instagram can change page structures and CDN URLs can expire. The Actor validates redirects against official Instagram hosts and is not a general-purpose URL resolver.

### Legal use, privacy, and support

Process only content you are authorized to access. Respect Instagram's terms, copyright, privacy law, and the rights of creators and subjects. A public media URL does not grant reuse rights. Use the **Issues** tab for support and the **API** tab for integration examples or custom solutions.

# Actor input Schema

## `postIdsOrUrls` (type: `array`):

Instagram shortcodes or HTTPS post, reel, TV, profile-prefixed reel, and share URLs.

## `maxConcurrency` (type: `integer`):

Maximum simultaneous Instagram page requests.

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

Uses GB residential proxies by default and switches to DE after a failed attempt.

## Actor input object example

```json
{
  "postIdsOrUrls": [
    "ABC123example",
    "https://www.instagram.com/reel/XYZ987example/"
  ],
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "GB"
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing one result per supplied post ID or share link.

# 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 = {
    "postIdsOrUrls": [
        "ABC123example",
        "https://www.instagram.com/reel/XYZ987example/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("spider_studio/instagram-media-download").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 = { "postIdsOrUrls": [
        "ABC123example",
        "https://www.instagram.com/reel/XYZ987example/",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("spider_studio/instagram-media-download").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "postIdsOrUrls": [
    "ABC123example",
    "https://www.instagram.com/reel/XYZ987example/"
  ]
}' |
apify call spider_studio/instagram-media-download --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,spider_studio/instagram-media-download"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/TUoYhtBGC7DiFTDAw/builds/UsOxco6kC83BaEQMu/openapi.json