🌟 Instagram Video Scraper and Downloader

One-line hero: Instantly fetch metadata and download from public Reels or posts — production-ready, privacy-safe, and built for fast batch runs in Apify Console.

---

📖 Short summary

This Actor extracts clean metadata for Instagram Reels/posts and (optionally) fetches downloadable media. It returns structured records to Dataset / Key-Value store and is designed for reliability, proxy-safety, and enterprise-scale runs.

---

💡 Use cases — When to use

• Bulk-collect metadata (title, author, upload date, views, likes) for analytics or feeds.
• Attach best-effort download links and optionally download media for archival or processing.
• Quick HTML metadata fallback when the primary scraper hits rate limits.
• Privacy-sensitive workflows where raw media links should be redacted.

---

⚡ Quick Start (Console — one-click)

Hero screenshot (Console run):

(Add a screenshot/GIF of the Console run here for best conversion.)

One-liner: Paste a list of startUrls into the Input pane and click Run — results appear in Dataset and Key-Value Store in seconds.

---

⚙️ Quick Start (CLI + API)

CLI (one-liner)

$apify run --token=<APIFY_TOKEN>

Python (apify-client) — minimal example

from apify_client import ApifyClient
client = ApifyClient(token="<APIFY_TOKEN>")
run_input = {
  "mode": "both",
  "startUrls": [{"url": "https://www.instagram.com/reel/SHORTCODE/"}],
  "desired_resolution": "1080p"
}
run = client.actor("your-username/your-actor").call(run_input=run_input)
print(run)

---

📝 Inputs (fields & schema)

Console JSON input example (also saved as input.example.json):

{
  "mode": "scrape",
  "startUrls": [
    {"url": "https://www.instagram.com/reel/SHORTCODE/"}
  ],
  "desired_resolution": "1080p",
  "download": false,
  "merge_if_ffmpeg": false,
  "cookie_file": "<COOKIE_FILE_STORE_KEY_OR_PATH>",
  "hide_media_links": true,
  "preserve_thumbnails": true,
  "maxConcurrency": 3,
  "preferred_proxy_type": "auto",
  "diagnostic": false
}

Tip: The Platform can validate inputs with an input schema. Provide startUrls as an array of objects {"url": "..."} for the Console UI.

---

⚙️ Configuration (actor inputs)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
mode	string	✅ Yes	"scrape"	"scrape" / "download"	Choose what to run (metadata vs media)
startUrls	array	✅ Yes	None	[{"url":"https://..."}]	List of target post/reel URLs
proxyConfiguration	object	⚙️ Optional	{}	{"useApifyProxy": true}	Override actor proxy settings
preferred_proxy_type	string	⚙️ Optional	"auto"	"residential"	Preferred proxy type for sessions
force_residential	boolean	⚙️ Optional	false	true	Alias to force residential proxy
download	boolean	⚙️ Optional	false	true	Whether to download media files
desired_resolution	string	⚙️ Optional	"1080p"	"720p"	Preferred media resolution (UI: string)
merge_if_ffmpeg	boolean	⚙️ Optional	false	true	Use system merger to combine audio+video (optional)
cookie_file	string	⚙️ Optional	None	"<COOKIE_FILE>"	Cookie file key if authenticated access is needed
hide_media_links	boolean	⚙️ Optional	true	false	Redact raw media URLs in output (privacy-safe)
preserve_thumbnails	boolean	⚙️ Optional	true	false	If false, thumbnails are redacted from output
maxConcurrency	integer	⚙️ Optional	3	5	Concurrency cap (1–10)
diagnostic	boolean	⚙️ Optional	false	true	Enable verbose logs for debugging

Example Console setup: Paste https://www.instagram.com/reel/SHORTCODE/ into startUrls input and click Run Actor.

---

📄 Outputs (Dataset / KV examples)

Example output (one record)

{
  "original_url": "https://www.instagram.com/reel/SHORTCODE/",
  "id": "SHORTCODE",
  "ownerUsername": "creator_handle",
  "description": "Post caption text",
  "likesCount": 1234,
  "likesDisplay": "1.2k",
  "commentsCount": 12,
  "commentsDisplay": "12",
  "videoViewCount": 45678,
  "viewsDisplay": "45.7k",
  "upload_date_iso": "2025-03-01T12:34:56Z",
  "upload_date": "1st March 2025",
  "thumbnail": "https://.../thumbnail.jpg",
  "download_links": {"merged_video": "https://..."},
  "_scraped_at": "2025-11-13T12:00:00Z",
  "_source_index": 1
}

Notes: Records are written to Dataset (rows) and a full array is stored in Key-Value under key OUTPUT.

---

🔑 Environment Variables

• APIFY_TOKEN — use in CLI / API calls. Use placeholder <APIFY_TOKEN> in examples.
• HTTP_PROXY / HTTPS_PROXY — optional when providing a custom proxy like <PROXY_USER:PASS@HOST:PORT>.

⚠️ Always store credentials as Secrets in Console (do not paste plaintext into input fields).

---

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

1. Apify Console — open the Actor, paste startUrls JSON, choose mode, click Run.
2. CLI — apify run --token=<APIFY_TOKEN> (ensure Actor is published or run from project folder).
3. API / apify-client — call the Actor run endpoint with run_input JSON (see snippet above).

Quick checklist before running

• Provide startUrls (required).
• If you need consistent sessions, enable proxyConfiguration or set preferred_proxy_type.
• Toggle hide_media_links to redact raw media URLs for privacy.

---

⏰ Scheduling & Webhooks

• Schedule recurring runs from the Console (Runs → Schedule) — pick frequency and input.
• Webhooks: configure a webhook on successful run completion to get run payloads (Dataset / Key-Value links) for automation.

---

🕾️ Logs & Troubleshooting

• Check Run logs in Console for step-by-step messages.

• Common issues:

  • No startUrls — actor exits early; supply startUrls array.
  • Rate limits / access errors — enable Proxy or try preferred_proxy_type: "residential".
  • Download fails — ensure download is enabled and proxy/cookie settings are correct.

Quick fixes: enable diagnostic: true for verbose logs, or reduce maxConcurrency to avoid bursts.

---

🔒 Permissions & Storage Notes

• Output storage: Dataset (records) and Key-Value (OUTPUT key) for full run JSON.
• Privacy-first defaults: hide_media_links = true, preserve_thumbnails = true.
• Do not store secrets in plain input — use Console Secrets or environment variables.

---

🔟 Changelog / Versioning (example)

• v1.0.0 — Initial public release: metadata-first scraper, HTML fallback, optional downloader, privacy defaults.

---

🖌 Notes / TODOs

• TODO: confirm output schema — inferred from the Actor but a formal schema.json will improve the Console UI.
• TODO: add demo GIF/screenshots (provide images or Console screenshots for best conversion).

---

🌍 Proxy configuration

Enable Apify Proxy (quick): In Console → Actor run Options → toggle Use Apify proxy.

Custom proxy (example env vars):

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

Notes

• Store proxy credentials as Console Secrets, not plaintext in inputs.
• The Actor supports session-aware proxy URLs for consistent sessions.
• TODO: Consider proxy rotation for large-scale scraping.

---

📚 References (official docs)

• How to create an Actor README — https://docs.apify.com/academy/actor-marketing-playbook/actor-basics/how-to-create-an-actor-readme
• Actor input schema — https://docs.apify.com/platform/actors/development/actor-definition/input-schema
• Apify CLI — https://docs.apify.com/cli/

---

🤔 What I inferred from main.py

• Primary behavior: metadata-first scraper for public Reels/posts with an HTML fallback when the primary scraper is rate-limited.
• Optional media extraction/download flow that selects best-resolution streams and can merge audio+video using a system merger when enabled.
• Uses a proxy configuration (session-aware) and exposes flags to prefer residential proxies.
• Outputs are written to Dataset and the Key-Value store under key OUTPUT.
• Defaults are privacy-focused: hide_media_links: true, preserve_thumbnails: true, and maxConcurrency capped.

---

Why this Actor?

Quick benefits: production-ready, privacy-safe defaults, plug-and-play in Console, and robust fallback for stable metadata collection. Run it now — get instant insights in seconds.

Run this Actor on Apify Console — get results instantly. { "mode": "scrape", "startUrls": [ {"url": "https://www.instagram.com/reel/SHORTCODE/"} ], "desired_resolution": "1080p", "download": false, "merge_if_ffmpeg": false, "cookie_file": "<COOKIE_FILE_STORE_KEY_OR_PATH>", "hide_media_links": true, "preserve_thumbnails": true, "maxConcurrency": 3, "preferred_proxy_type": "auto", "diagnostic": false }

CONFIG.md — Advanced configuration & proxy notes

This optional config file explains advanced options and recommended Console setup for high-volume or sensitive runs.

Proxy & session hygiene

• Prefer using the Actor's Proxy configuration option in Console (actor run Options) for session-aware URLs.
• If you provide a custom proxy, store credentials as a Console Secret and reference them via environment variables or proxyConfiguration input.

Example env vars

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

Large-scale / reliability tips

• Use preferred_proxy_type: "residential" for heavy runs when access errors occur.
• Lower maxConcurrency to reduce bursts when you encounter rate limits.
• Enable diagnostic: true to collect detailed logs for support triage.

Security & privacy

• hide_media_links defaults to true — keep it enabled if you must not expose direct media URLs.
• preserve_thumbnails defaults to true — set false to redact thumbnails as well.

TODOs

• Add an INPUT_SCHEMA.json to the repo for Console UI form validation.
• Add demo screenshots/GIFs to README for higher conversion.