🌟 Advanced Instagram Reels Scraper — Console-Ready Actor

Hero: Instant, privacy-safe extraction of public Instagram Reels — get structured video metadata and download-ready links in seconds.

---

📖 Short summary

A production-ready Apify Actor that reliably extracts metadata and media references from public Instagram posts and Reels. Plug into Apify Console, run one-click, and receive clean JSON records suitable for analytics, archiving, or automated downloads. Secure-by-design and built for scale.

---

💡 Use cases / When to use

• Collect batch metadata for Instagram Reels or feed videos for analytics.
• Build datasets for social listening, content research, or media archiving.
• Download video/audio resources for downstream processing (when allowed).
• Feed data into BI tools or ML pipelines.

---

⚡ Quick Start — Console (one-click)

1. Open this Actor in Apify Console.
2. Paste one or more public Instagram post/reel URLs into Input (see example below).
3. (Optional) Enable Apify Proxy in Console settings if scraping at scale.
4. Click Run — results will stream to the dataset and be saved to key-value store OUTPUT.

---

⚙️ Quick Start — CLI & API

CLI (apify-cli)

$apify run --input input.example.json

Python (apify-client) — minimal snippet

from apify_client import ApifyClient
client = ApifyClient('<APIFY_TOKEN>')
run = client.actor('your-username/instagram-reels-scraper').call(run_input={
    'startUrls': [ {'url': 'https://www.instagram.com/reel/XXXX/'} ],
    'download': False,
    'desired_resolution': '1080p'
})
print(run)

---

📝 Inputs (fields & schema)

Provide input as a JSON object. The actor accepts the following fields:

{
  "startUrls": [{ "url": "https://www.instagram.com/reel/1234567890123456/" }],
  "download": false,
  "desired_resolution": "1080p",
  "proxyConfiguration": { "useApifyProxy": true }
}

Field summary:

• startUrls — array of URLs (required). Can be strings or { "url": "..." } objects.
• download — boolean (optional). If true, the actor will attempt to download media resources referenced in the extracted formats.
• desired_resolution — string (optional). Example: "1080p", "720p".
• proxyConfiguration — object (optional). Standard Apify proxy configuration.

---

⚙️ Configuration

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	[{"url":"https://www.instagram.com/reel/123/"}]	One or more public post/reel URLs
download	boolean	⚙️ Optional	false	true	Download media files when available (use proxies & storage)
desired_resolution	string	⚙️ Optional	1080p	720p	Preferred target resolution for video selection
proxyConfiguration	object	⚙️ Optional	{}	{ "useApifyProxy": true }	Use proxies for scale / geo-unblocking

Console example: paste a single URL into Input > startUrls and click Run Actor.

---

📄 Outputs (Dataset / KV examples)

The Actor pushes transformed records to the Dataset (streamed) and stores the full result array in Key-Value store under key OUTPUT.

Example single output record (transformed):

{
  "original_url": "https://www.instagram.com/reel/1234567890123456/",
  "id": "1234567890123456",
  "ownerUsername": "example_user",
  "description": "Short caption text",
  "likesCount": 1200,
  "likesDisplay": "1.2k ❤️",
  "commentsCount": 45,
  "viewsDisplay": "12.3k 👀",
  "upload_date": "14th October 2025",
  "duration_seconds": 32,
  "duration_display": "32 Seconds (0.0089 Hours)",
  "formats": [ { "type": "video", "url": "https://...mp4", "duration": 32 } ],
  "download_links": { /* if download requested */ },
  "ai_insight": "General content reel 🌀",
  "randomExtraInfo": { "scrapeBatch": "Reel-Set-05", "regionCode": "US" }
}

Key-Value store: OUTPUT contains the array of all returned records for the run.

---

🔑 Environment Variables

Use placeholders for secrets. Store them in Console secrets or Actor settings — never embed in code.

• APIFY_TOKEN — placeholder for Apify API access (use Console secrets)
• IG_USER — optional Instagram username for authenticated fetches (placeholders only)
• IG_PASS — optional Instagram password (placeholders only)

---

▶️ How to Run (Console / CLI / API)

Console: paste startUrls input, optionally enable Apify Proxy, click Run.

CLI: apify run --input input.example.json.

API: Use apify-client to call actor with run_input shown above.

---

⏰ Scheduling & Webhooks

• Use the Apify Console scheduler to run this Actor on a cron expression (daily/hourly).
• Configure webhooks in Console to be notified on run success/failure. Push the OUTPUT KVS link to downstream systems.

---

🕾️ Logs & Troubleshooting

• Logs stream live in Console. Look for 🎬 preview lines to confirm successful extraction.

• Common issues:

  • Unsupported URL — ensure the URL is a public Instagram post or reel (/reel/ or /p/ style).
  • Authentication required — private posts require login credentials or cookies (use secrets).
  • Region/Rate errors — enable proxies.

---

🔒 Permissions & Storage Notes

• The Actor only fetches public content by default. Do not use this Actor to access private content without explicit permission.
• Store credentials and tokens securely in Console secrets — never in plain input JSON.
• Respect Instagram terms of service and applicable laws when collecting or storing media.

---

🔟 Changelog / Versioning

• v1.0 — Initial Console-ready Actor: public extraction, format normalization, optional media download, proxy support.
• TODO: Add semantic versioning tags for future releases.

---

🖌 Notes / TODOs

• TODO: Confirm expected output schema for download_links when download is enabled (reason: download outputs may vary across platforms).
• TODO: Add built-in rate-limit detection to automatically pause between burst runs.

---

🌍 Proxy configuration

This Actor supports proxy usage and will use the proxyConfiguration input when provided.

Enable Apify Proxy (Console) — one-line:

• In the Console run dialog, toggle Use Apify Proxy.

Custom proxies (example formats):

• Single proxy (HTTP): http://<PROXY_USER:PASS@HOST:PORT>
• HTTPS example: https://<PROXY_USER:PASS@HOST:PORT>

Environment-style examples:

HTTP_PROXY=http://<PROXY_USER:PASS@HOST:PORT>
HTTPS_PROXY=https://<PROXY_USER:PASS@HOST:PORT>

Security note: store credentials as Console secrets, not plaintext in inputs.

Advanced note / TODO: TODO: Consider proxy rotation for large-scale scraping to improve reliability and avoid rate-limits.

---

📚 References

• Apify Actor README guidelines (official docs)
• Apify Input/Output schema docs (official docs)
• Apify CLI & API usage docs (official docs)

---

🤔 What I inferred from src/main.py

• The Actor accepts startUrls and supports both /reel/ and /p/ post URLs.
• It normalizes metadata (likes, comments, views) and formats durations into human-friendly strings.
• It supports optional authenticated fetches via IG_USER / IG_PASS environment variables (placeholders only).
• It writes streamed records to Dataset and saves a full run array to Key-Value store key OUTPUT.
• Proxy configuration is supported and the Actor will use proxy sessions when supplied.

---

---

Files included in this canvas

• README.md (this document)
• input.example.json (JSON example below)
• CONFIG.md (quick config tips)

---

input.example.json

{
  "startUrls": [
    { "url": "https://www.instagram.com/reel/1234567890123456/" },
    { "url": "https://www.instagram.com/p/ABCDEFGHIJK/" }
  ],
  "download": false,
  "desired_resolution": "1080p",
  "proxyConfiguration": { "useApifyProxy": true }
}

---

CONFIG.md (quick tips)

# Use Console secrets for APIFY_TOKEN, IG_USER, IG_PASS
# Enable Apify Proxy for large-scale runs
# Respect target site terms and privacy