Instagram Posts & Reels List – Bulk Content Metadata Scraper

Retrieve the full list of posts and reels from any Instagram profile using its list_id. Get partial metadata, thumbnails, captions, dates, likes, comments, and media URLs for every post and reel in bulk. Filter by date to get only recent content.

---

📚 API Documentation

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

Transcript Downloader API Documentation

Get Your API Key • API Pricing

---

✨ Features

• 📸 Complete list download: Get all posts and reels from a profile
• 🎬 Multiple content types: Posts, reels, carousels, images, videos
• 📅 Date filtering: Limit results to content posted within the last N days
• 📊 Rich metadata: Likes, comments, views, engagement scores, hashtags
• 👥 Relationship data: Tagged users, coauthors, partnerships, audio info
• 🔁 Batch processing: Handle multiple lists simultaneously
• ⚙️ Concurrency control: Adjust processing speed with configurable limits
• 🔄 Automatic polling: Waits for list scraping when enabled (typically 3-5 min)
• 🚦 Rate limiting: Built-in delays to respect API limits
• 💰 Cost tracking: Monitor API usage per list
• 🧠 Error tracking: All failures logged with detailed error information
• ⚡ Cached results: Returns cached data for recent successful jobs

---

🔧 Input Parameters

The actor accepts the following input:

Parameter	Type	Required	Default	Description
listIds	array	✅ Yes	-	List of Instagram list IDs (from profile endpoint)
apiToken	string	✅ Yes	-	Your Transcript Downloader API bearer token
waitForCompletion	boolean	No	true	Whether to wait for complete list scraping
maxWaitTime	number	No	15	Max time to wait for scraping completion (1-30 minutes)
pollingInterval	number	No	180	How often to check status when waiting. API recommends 180s for lists (10-300 seconds)
maxConcurrency	number	No	2	Max concurrent list requests (range: 1-5)
maxAgeDays	number	No	-	Only return content posted within the last N days (0-999999). Leave empty for all content

📥 Sample Input

{
  "listIds": [
    "01K575ZB8HT9BY4QATJ7848BVK",
    "01K575ZB8HT9BY4QATJ784DJN"
  ],
  "apiToken": "your-api-token",
  "waitForCompletion": true,
  "maxWaitTime": 15,
  "pollingInterval": 180,
  "maxConcurrency": 2,
  "maxAgeDays": 30
}

📝 How to Get List IDs

List IDs are obtained from the Instagram Profile Scraper response:

{
  "list": {
    "list_id": "01K575ZB8HT9BY4QATJ7848BVK",
    "list_cost": "12.500"
  }
}

Workflow:

1. Use Instagram Profile Scraper to get profile data
2. Extract list.list_id from the response
3. Use this list ID in this actor to get all posts/reels

---

📤 Output Format

Each list will produce a dataset item with the following structure:

Successful Response

{
  "listId": "01K575ZB8HT9BY4QATJ7848BVK",
  "status": "success",
  "items": [
    {
      "type": "post",
      "instagram_id": "3780275965541531021",
      "caption": null,
      "description": "Beautiful post description",
      "likes": 11,
      "comments": 5,
      "num_comments": 5,
      "date_posted": "2025-12-04 16:00:33",
      "user_posted": "username",
      "account": "username",
      "image_url": "https://scontent.cdninstagram.com/...",
      "video_url": null,
      "url": "https://www.instagram.com/p/ABC123/",
      "shortcode": "ABC123",
      "content_type": "Image",
      "photos_number": 0,
      "videos_duration": null,
      "location": null,
      "post_id": "3780275965541531021",
      "datetime": "2025-12-04 16:00:33",
      "photos": ["https://image1.jpg"],
      "videos": [],
      "images": ["https://image1.jpg"],
      "audio": []
    },
    {
      "type": "reel",
      "post_id": "3780273348857873344",
      "description": "Reel description with #hashtags",
      "likes": 25000,
      "views": 0,
      "video_view_count": 0,
      "video_play_count": 480000,
      "num_comments": 1200,
      "date_posted": "2025-12-04 15:55:45",
      "user_posted": "username",
      "account": "username",
      "video_url": null,
      "thumbnail": "https://thumbnail.jpg",
      "url": "https://www.instagram.com/reel/XYZ789/",
      "shortcode": "XYZ789",
      "content_type": "reel",
      "content_id": "reel_content_123",
      "product_type": "clips",
      "length": null,
      "videos_duration": null,
      "is_verified": false,
      "videos": [null]
    }
  ],
  "posts": [
    /* Array of posts only (filtered from items) */
  ],
  "reels": [
    /* Array of reels only (filtered from items) */
  ],
  "summary": {
    "totalItems": 21,
    "totalPosts": 20,
    "totalReels": 1,
    "totalCost": "0.149",
    "processingTime": "125.3s"
  },
  "downloadInfo": {
    "posts": {
      "id": "01KBNV7FBDJ1JZNPM6YEYBYG0E",
      "media_id": "77007569848",
      "type": "instagram_list_posts",
      "cost": "0.142",
      "status": "success",
      "response": null,
      "created_at": "2025-12-04T23:30:36.000000Z"
    },
    "reels": {
      "id": "01KBNV7FBJR0QZ9A2PEVVC279N",
      "media_id": "77007569848",
      "type": "instagram_list_reels",
      "cost": "0.007",
      "status": "success",
      "response": null,
      "created_at": "2025-12-04T23:31:40.000000Z"
    }
  },
  "message": "List downloading completed successfully."
}

Pending Response (when waitForCompletion is false)

{
  "listId": "01K575ZB8HT9BY4QATJ7848BVK",
  "status": "pending",
  "downloads": [
    {
      "id": "01KBNRQPSP8WXHSVPJ7CNBQEBP",
      "media_id": "77007569848",
      "type": "instagram_list_posts",
      "cost": "0.075",
      "status": "pending",
      "response": null,
      "created_at": "2025-12-04T22:46:42.000000Z"
    },
    {
      "id": "01KBNRQPSW2BDZD2N5WKP79VGT",
      "media_id": "77007569848",
      "type": "instagram_list_reels",
      "cost": "0.075",
      "status": "pending",
      "response": null,
      "created_at": "2025-12-04T22:46:42.000000Z"
    }
  ],
  "message": "List downloading is in progress.",
  "summary": {
    "processingTime": "2.1s"
  }
}

Failed Response

{
  "listId": "01K575ZB8HT9BY4QATJ7848BVK",
  "error": "Profile not found - Fetch profile first before requesting list",
  "status": "failed"
}

---

🚀 How to Use

Complete Workflow

Step 1: Get profile and list ID

// Run Instagram Profile Scraper first
{
  "profileUrls": ["https://www.instagram.com/mrbeast"],
  "apiToken": "your-token"
}

Step 2: Extract list_id from response

{
  "list": {
    "list_id": "01K575ZB8HT9BY4QATJ7848BVK"
  }
}

Step 3: Run this actor with the list_id

{
  "listIds": ["01K575ZB8HT9BY4QATJ7848BVK"],
  "apiToken": "your-token",
  "waitForCompletion": true,
  "maxAgeDays": 90
}

Tip: Omit maxAgeDays to get all posts/reels, or set it to limit results to recent content only.

---

❌ Error Handling

The actor gracefully handles common API errors:

Status Code	Meaning	Action
400	Incorrect ID or media restricted	Check list ID format
401	Insufficient credits or invalid token	Check credits and API token
403	Invalid API token	Regenerate API token
404 (List)	Invalid Download List ID	Verify list ID is correct
404 (Profile)	Profile not found - Fetch profile first	Run profile scraper first
429	Rate limit exceeded	Actor handles with delays
500	Third party service error or processing error	Retry automatically
503	Service temporarily unavailable	Retry later

Failed lists are captured in the dataset with error information.

---

⚠️ 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
Cached results (recent jobs)	Instant	-
Small-medium profiles	3-15 minutes	60 minutes
Large profiles (1000+ posts)	15-60 minutes	3 hours

Polling

The API recommends polling every 180 seconds (3 minutes) for list operations. The actor defaults to this interval. You can lower it for smaller profiles, but avoid going below 60 seconds when processing many lists concurrently.

Retry Behavior

The actor automatically retries on transient errors (429, 500, 503) with exponential backoff. 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)

---

💡 Best Practices

For Standard Lists

{
  "listIds": ["01K575ZB8HT9BY4QATJ7848BVK"],
  "apiToken": "your-token",
  "waitForCompletion": true,
  "maxWaitTime": 15,
  "pollingInterval": 180,
  "maxConcurrency": 2
}

Use case: Normal profiles with up to ~1000 posts

For Large Profiles

{
  "listIds": ["01K575ZB8HT9BY4QATJ7848BVK"],
  "apiToken": "your-token", 
  "waitForCompletion": true,
  "maxWaitTime": 30,
  "pollingInterval": 180,
  "maxConcurrency": 1
}

Use case: Large profiles with thousands of posts

For Recent Content Only

{
  "listIds": ["01K575ZB8HT9BY4QATJ7848BVK"],
  "apiToken": "your-token",
  "waitForCompletion": true,
  "maxWaitTime": 15,
  "pollingInterval": 180,
  "maxAgeDays": 30
}

Use case: Only posts/reels from the last 30 days — faster processing, lower cost

General Tips

• ✅ Always run profile scraper first to get list_id
• ✅ Use waitForCompletion: true for complete data (recommended)
• ✅ Keep maxConcurrency low (1-2) to avoid rate limits
• ✅ Use maxAgeDays to limit results when you only need recent content
• ✅ Monitor costs using the summary.totalCost field
• ✅ Cached results return instantly for recent successful requests
• ✅ Set higher maxWaitTime for profiles with many posts
• ✅ Keep default pollingInterval of 180 seconds as recommended by the API
• ✅ Lists are sorted by date_posted in descending order (newest first)

---

📊 Data Included

For Posts:

• Basic metadata (likes, comments, date, caption, description)
• Instagram ID and post ID
• Content type (Image, Video, Carousel)
• Image URLs (photos, images arrays)
• Video URLs (videos array)
• Audio URLs (audio array)
• Location information
• User information (user_posted, account)
• Post URL and shortcode
• Date/time information (date_posted, datetime)
• Photo and video counts

For Reels:

• Video URL and thumbnail
• Views and play counts (views, video_view_count, video_play_count)
• Content identifiers (post_id, content_id, shortcode)
• Product type and content type
• Duration/length information
• Verification status (is_verified)
• Video array
• Engagement metrics (likes, comments)

---

🔗 List ID Format

List IDs are 26-character alphanumeric strings:

✅ 01K575ZB8HT9BY4QATJ7848BVK (valid format)
❌ ABC123 (too short)
❌ 01k575zb8ht9by4qatj7848bvk (must be uppercase)

---

📈 Monitoring & Analytics

Track your usage with the built-in summary data:

{
  "summary": {
    "totalItems": 21,
    "totalPosts": 20,
    "totalReels": 1,
    "totalCost": "0.149",
    "processingTime": "125.3s"
  }
}

Use this data to:

• Monitor API costs per list
• Track processing performance
• Analyze content distribution (posts vs reels)
• Plan batch processing strategies

---

💳 Pricing & Billing

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

• Profile request: Initiates list scraping (separate charge)
• List download: Charges apply based on profile size
• Cached results: No additional charge for recent successful jobs
• Cost displayed: Total cost shown in downloadInfo.cost field

📊 Pricing varies by profile size and content volume. Visit our site to checkout pricing.
View full details and subscription plans on our pricing page

---

🎯 Use Cases

• Content Analysis: Analyze posting patterns, content types, engagement trends
• Competitor Research: Track competitors' content strategy, hashtags, partnerships
• Influencer Marketing: Evaluate influencer content, engagement rates, brand partnerships
• Brand Monitoring: Monitor brand mentions, tagged content, user engagement
• Market Research: Identify trending content, popular hashtags, audio tracks
• Social Listening: Track conversations, comments, engagement on all posts
• Archive Creation: Create complete backup of profile content
• Performance Tracking: Monitor engagement scores, views, likes over time

---

🔄 Integration with Profile Scraper

This actor works seamlessly with the Instagram Profile Scraper:

1. Profile Scraper → Get basic profile info + ~12 recent posts + list_id
2. List Scraper (this actor) → Get ALL posts/reels with metadata using list_id
3. Post Detail Scraper → Get complete metadata for individual posts (future actor)

---

🙋 Support

Need help? Visit Transcript Downloader Support. 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.