# Instagram Audio – Reel & Post Audio Downloader (`transcriptdl/instagram-audio---reel-post-audio-downloader`) Actor

Verified 99.4% Success. BULK process and extract audio from Instagram reels and posts using a URL. Returns a downloadable file when available or indicates when the post has no audio.

- **URL**: https://apify.com/transcriptdl/instagram-audio---reel-post-audio-downloader.md
- **Developed by:** [Transcript Downloader](https://apify.com/transcriptdl) (community)
- **Categories:** AI, Automation, Social media
- **Stats:** 28 total users, 1 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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

## 🎵 Transcript Downloader - Instagram Audio Scraper Extractor & Downloader

Convert Instagram reels and video posts into downloadable audio files using the Transcript Downloader API. Ideal for music extraction, content repurposing, and offline listening. Works in bulk, with optional storage to Apify key-value store.

***

### 📚 API Documentation

For complete API reference, endpoint details, and advanced usage examples, visit our official documentation:

**[Transcript Downloader API Documentation](https://documentation.transcriptdownloader.com)**

**[Get Your API Key](https://dashboard.transcriptdownloader.com/settings)** • **[API Pricing](https://transcriptdownloader.com/#pricing)**

***

### ✨ Features

- 📁 **Bulk processing** of multiple Instagram content URLs
- 🎬 **Supports reels and posts** with video content
- 🖼️ **Image detection** - identifies image-only posts (no audio)
- 🕒 **Polling logic** with automatic retries
- 🧠 **Progress tracking** and run logs
- 🗂️ **Optional Apify file storage** to key-value store
- 🔔 **Webhook support**: Receive results via webhook instead of polling
- 🔐 **Secure API token-based authentication**

***

### 🔧 Input Parameters

| Parameter         | Type    | Required | Default | Description                                                     |
| ----------------- | ------- | -------- | ------- | --------------------------------------------------------------- |
| `contentUrls`     | array   | ✅ Yes    | –       | List of Instagram post/reel URLs to extract audio from          |
| `apiToken`        | string  | ✅ Yes    | –       | Bearer token for Transcript Downloader API                      |
| `downloadToApify` | boolean | No       | `true`  | Whether to download audio files to Apify key-value store        |
| `maxWaitTime`     | number  | No       | `10`    | Max time to wait for audio processing (in minutes, range: 1–15) |
| `pollingInterval` | number  | No       | `30`    | Interval between polling status (in seconds, range: 30–300)     |
| `includeWebhook`  | string  | No       | –       | Webhook URL to receive results when audio processing completes. Must be publicly reachable and accept POST requests |

📥 **Example Input**

```json
{
  "contentUrls": [
    "https://www.instagram.com/reel/ABC123",
    "https://www.instagram.com/p/XYZ789"
  ],
  "apiToken": "your-api-token",
  "downloadToApify": true,
  "maxWaitTime": 10,
  "pollingInterval": 30
}
```

***

### 📤 Output Format

Each content URL generates an output record with metadata and processing info:

#### Successful Response (Audio Extracted)

```json
{
  "contentUrl": "https://www.instagram.com/reel/ABC123",
  "id": "01KB21QX05P6B4JA7FJHTM7AWE",
  "type": "instagram_audio",
  "status": "success",
  "duration": "00:00:30",
  "cost": "0.050",
  "audio_url": "https://drive.transcriptdownloader.com/audios/instagram-ABC123xyz.mp3?Expires=...",
  "storage_key": "instagram-ABC123.mp3"
}
```

#### No Audio Response (Image-Only Post)

```json
{
  "contentUrl": "https://www.instagram.com/p/XYZ789",
  "status": "no_audio",
  "message": "This content does not contain audio.",
  "download_id": "01KB21QX05P6B4JA7FJHTM7AWE",
  "cost": "0.025"
}
```

#### Failed Response

```json
{
  "contentUrl": "https://www.instagram.com/p/INVALID",
  "status": "failed",
  "error": "Invalid Instagram URL. Must be a post (/p/) or reel (/reel/) URL."
}
```

***

### 🚀 How to Use

1. Get your API token from [Transcript Downloader](https://dashboard.transcriptdownloader.com/settings)
2. Add one or more Instagram post/reel URLs (must include `/p/` or `/reel/`)
3. Set `downloadToApify` to `true` if you want files saved to storage
4. Run the actor and access results in the dataset or key-value store

***

### 🔗 Supported URL Formats

The actor supports Instagram post and reel URLs:

```
✅ https://www.instagram.com/p/SHORTCODE
✅ https://www.instagram.com/reel/SHORTCODE
✅ http://www.instagram.com/p/SHORTCODE
✅ https://instagram.com/reel/SHORTCODE (without www)
```

❌ Not supported:

```
❌ Profile URLs (https://www.instagram.com/username/)
❌ Story URLs
```

***

### ❌ Error Handling

This actor includes robust handling for common issues:

| Status Code | Description                                            |
| ----------- | ------------------------------------------------------ |
| `400`       | Invalid Instagram URL – must be post or reel           |
| `401`       | Invalid API key or insufficient credits                |
| `403`       | Invalid API token – check or regenerate key            |
| `429`       | Too many requests – reduce polling frequency           |
| `500`       | Server error – failed to initiate content fetch        |
| `503`       | Transcript Downloader API under maintenance            |

#### Special Cases

- **Image-only posts**: Detected automatically and marked as `no_audio` status
- **Private accounts**: May return errors if content is not accessible
- **Deleted content**: Will fail with appropriate error message

***

### ⚠️ Rate Limiting & Performance

#### API Rate Limits

| Scope | Limit | Window |
| ----- | ----- | ------ |
| Per User (API Token) | 90 requests | 1 minute |
| Per IP (unauthenticated) | 90 requests | 1 minute |

When rate limits are exceeded, the API returns `429 Too Many Requests`. The actor handles this automatically with built-in retry logic.

#### Processing Times

| Scenario | Typical Duration | Maximum Wait | Recommended Poll Interval |
| -------- | ---------------- | ------------ | ------------------------- |
| Audio Extraction | 10 seconds - 5 minutes | 15 minutes | 30 seconds |
| Image-only posts (detection) | ~5-10 seconds | - | - |

Breakdown by content length:

- **Short reels** (< 30 seconds): ~30-90 seconds
- **Medium videos** (30s - 2 minutes): ~1-3 minutes
- **Long videos** (2-5 minutes): ~2-5 minutes
- **Download to Apify**: Additional 5-15 seconds per file when enabled

#### Retry Behavior

The actor automatically retries on transient errors (429, 500, 503) with exponential backoff (base delay 1s, max delay 60s, up to 5 attempts). It does **not** retry on client errors (401, 403, 404) since those require user action.

#### Response Headers

The API returns rate limit headers you can monitor in logs:

| Header | Description |
| ------ | ----------- |
| `X-RateLimit-Limit` | Max requests allowed in window |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `Retry-After` | Seconds to wait before retrying (on 429) |

***

### 🔔 Webhook Support

Instead of polling, you can receive results automatically via webhook. Pass a publicly reachable URL in the `includeWebhook` field, and the API will POST the results directly to your server when audio processing completes.

#### How It Works

1. The webhook URL is sent with the **initial API request only** (not during polling)
2. One webhook is fired per content item when processing completes or fails
3. The webhook payload is the exact same JSON the API endpoint would return
4. Failed deliveries are retried up to 3 times (at 10s, 30s, and 60s intervals)

#### Webhook Headers

Each delivery includes these custom headers to identify the event:

| Header | Description |
| ------ | ----------- |
| `X-Webhook-Endpoint` | `instagram/audio` |
| `X-Webhook-Original-Status` | HTTP status code of the result (e.g. `200`) |
| `X-Webhook-Download-Id` | The download record ID |

#### Example with Webhook

```json
{
  "contentUrls": [
    "https://www.instagram.com/reel/ABC123",
    "https://www.instagram.com/p/XYZ789"
  ],
  "apiToken": "your-token",
  "includeWebhook": "https://your-domain.com/webhook"
}
```

#### Important Notes

- The URL must be publicly reachable (no localhost or private IPs)
- Your endpoint must accept **POST** requests and return a `2xx` status
- Test your webhook URL first using the [API test endpoint](https://documentation.transcriptdownloader.com)
- The webhook is registered once at request time — it cannot be added after a job has started

***

### 💡 Best Practices

- ✅ Respect rate limits to avoid 429 errors
- ⏳ Use polling wisely — longer intervals for large queues
- ⏳ Keep `pollingInterval` at 30 seconds as recommended by the API
- 🔐 Keep your `apiToken` secret (never log it)
- 🧠 Monitor output for incomplete or failed downloads
- 🖼️ Check for `no_audio` status on image-only posts
- 🗂️ Store large audio files in Apify only when needed
- 🎯 Mix posts and reels in the same run

***

### 💰 Pricing & Billing

The Transcript Downloader API used by this actor requires a valid API token. API usage is billed separately:

- **Audio extraction**: ~$0.05 per reel/video post
- **Image-only detection**: ~$0.025 per post (no audio extracted)
- **Cost displayed**: Exact cost shown in each response

📊 Very cost-effective for bulk audio extraction.\
View full details and subscription plans on our [pricing page](https://transcriptdownloader.com/#pricing)

***

### 🎯 Use Cases

- 🎵 **Music extraction**: Extract audio from Instagram reels
- 📻 **Content repurposing**: Convert video content to audio format
- 🎙️ **Podcast creation**: Extract audio for podcast episodes
- 📱 **Offline listening**: Download audio for offline access
- 🔊 **Audio analysis**: Extract audio for transcription or analysis
- 🎬 **Video to audio**: Batch convert Instagram videos to MP3

***

### 📊 Monitoring & Analytics

Track your usage with the built-in logging:

- **Total processed**: Number of URLs processed
- **Successful**: Audio files successfully extracted
- **No audio**: Image-only posts detected
- **Failed**: URLs that encountered errors
- **Success rate**: Percentage of successful extractions

Example summary:

```
Instagram Audio Scraper completed {
  totalProcessed: 10,
  successful: 7,
  noAudio: 2,
  failed: 1,
  successRate: '70.0%'
}
```

***

### 🔄 Integration with Other Actors

This actor works with the Instagram suite:

1. **Profile Scraper** → Get profile + recent posts
2. **List Scraper** → Get all posts/reels from profile
3. **Audio Scraper (this actor)** → Extract audio from reels/posts

**Complete Workflow**:

```
Profile → List → Filter Videos → Extract Audio
```

***

### 🙋 Support

Need help? Visit [Transcript Downloader Support](https://www.transcriptdownloader.com/#contact).
We respond within 24 business hours.

For technical issues with this actor, check the run logs for detailed error messages.

***

### 📄 License

This actor is provided under the [ISC License](https://opensource.org/licenses/ISC).

***

**Made with ❤️ by Transcript Downloader** | [Website](https://www.transcriptdownloader.com) | [API Dashboard](https://dashboard.transcriptdownloader.com)

# Actor input Schema

## `contentUrls` (type: `array`):

List of Instagram post or reel URLs to extract audio from

## `apiToken` (type: `string`):

Bearer token for Transcript Downloader API authentication. Get it from https://dashboard.transcriptdownloader.com/settings

## `downloadToApify` (type: `boolean`):

Whether to download audio files to Apify key-value store

## `maxWaitTime` (type: `integer`):

Maximum time to wait for audio processing (1-15 minutes)

## `pollingInterval` (type: `integer`):

How often to check download status (minimum 30 seconds due to rate limits)

## Actor input object example

```json
{
  "contentUrls": [
    "https://www.instagram.com/reel/ABC123",
    "https://www.instagram.com/p/XYZ789"
  ],
  "downloadToApify": true,
  "maxWaitTime": 10,
  "pollingInterval": 30
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("transcriptdl/instagram-audio---reel-post-audio-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("transcriptdl/instagram-audio---reel-post-audio-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 '{}' |
apify call transcriptdl/instagram-audio---reel-post-audio-downloader --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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