👑 Instagram Video Scraper and Downloader Premium 👑

One-liner (hero): Instant, production-ready Instagram Reels metadata extraction and optional high-quality downloads — plug into Apify Console and get structured results in seconds.

---

📖 Short summary

This Actor extracts rich metadata for Instagram posts (reels & single posts), enriches values for analytics (human-friendly dates, durations, short counts), and — optionally — fetches high-quality download links and performs downloads/merges when requested. Safe defaults hide raw media links; proxy-friendly and resilient to rate limits.

---

💡 Use cases / When to use

• Bulk metadata collection for analytics, search indices or ML features.
• Scheduled monitoring of creators or campaigns.
• One‑click archival of media (download optional) with resumable, best-effort downloads.
• Quick metadata enrichment before ingest to databases or BI tools.

---

⚡ Quick Start (Console — one-click)

1. Open the Actor page in Apify Console.
2. Paste one or more Instagram post/reel URLs into the Input tab (see input.example.json).
3. Click 🔊 Run — results will appear in Dataset and under KVS key OUTPUT.

Tip: enable diagnostic: true for verbose logs if something looks off.

---

⚙️ Quick Start (CLI + API)

CLI (one-liner)

$apify run --input input.example.json

Python (apify-client)

from apify_client import ApifyClient
client = ApifyClient(token="<APIFY_TOKEN>")
run = client.actor("your-username/your-actor").call(
    run_input={
        "startUrls": ["https://www.instagram.com/reel/SHORTCODE/"],
        "mode": "scrape"
    }
)
# On completion, read dataset or key-value store (key: OUTPUT)

---

📝 Inputs (fields & schema)

Accepted input: JSON object. startUrls accepts an array of string URLs or objects { "url": "..." }.

Minimal Console JSON example (drop into the Input tab or save as input.example.json):

{
  "startUrls": [
    "https://www.instagram.com/reel/SHORTCODE/"
  ],
  "mode": "scrape",
  "desired_resolution": "1080p",
  "download": false,
  "merge_if_ffmpeg": false,
  "hide_media_links": true,
  "preserve_thumbnails": true,
  "maxConcurrency": 3,
  "diagnostic": false,
  "suppress_errors": true
}

Field reference (short)

• startUrls (array) — required. List of post/reel URLs (strings or { "url": "..." }).
• mode (string) — "scrape" | "download" | "both". Default: "scrape".
• desired_resolution (string) — preferred resolution for downloads (e.g. "1080p").
• download (boolean) — whether to download media (best-effort).
• merge_if_ffmpeg (boolean) — merge audio+video if ffmpeg is available.
• cookie_file (string) — optional secret reference for cookies (use Console secrets).
• hide_media_links (boolean) — hides raw formats URLs in output (default true).
• preserve_thumbnails (boolean) — keep thumbnails even when links are hidden (default true).
• maxConcurrency (integer) — [1..10], default 3.
• diagnostic (boolean) — verbose logging & raw data (default false).
• suppress_errors (boolean) — if true non-fatal errors are suppressed from logs (default true).
• proxyConfiguration (object) — optional Console proxy input object (see Proxy Configuration below).
• preferred_proxy_type / force_residential — hints to prefer residential proxies when creating a proxy configuration.

---

⚙️ Configuration (friendly table)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	["https://.../reel/ABC123/"]	URLs to scrape/download.
mode	string	✅ Yes	"scrape"	"both"	Choose scrape, download, or both.
desired_resolution	string	⚙️ Optional	"1080p"	"720p"	Preferred resolution for extraction.
download	boolean	⚙️ Optional	false	true	If true, attempts downloads.
merge_if_ffmpeg	boolean	⚙️ Optional	false	true	Requires ffmpeg in runtime to merge streams.
cookie_file	string	⚙️ Optional	None	"INPUT:INSTAGRAM_COOKIES"	Pass cookie secret (Console secret recommended).
hide_media_links	boolean	⚙️ Optional	true	false	Hides raw media URLs in output.
preserve_thumbnails	boolean	⚙️ Optional	true	false	Keep thumbnail preview images.
maxConcurrency	integer	⚙️ Optional	3	6	Controls parallelism (1..10).
diagnostic	boolean	⚙️ Optional	false	true	Verbose logging for debugging.
suppress_errors	boolean	⚙️ Optional	true	false	Set to false to surface errors in logs.
proxyConfiguration	object	⚙️ Optional	None	(Apify proxy object)	Provide proxy settings via Console.

Example Console setup: paste https://www.instagram.com/reel/ABC123/ into startUrls and click Run.

---

📄 Outputs (Dataset / Key-Value examples)

Where results are written

• Key-Value store: key OUTPUT (contains the full results array).
• Also each item is pushed to the default Dataset for easy CSV/JSON export.

Metadata-only example (scrape mode) — full duration fields included

{
  "original_url": "https://www.instagram.com/reel/ABC123/",
  "id": "ABC123",
  "ownerUsername": "creator_handle",
  "ownerFullName": "Creator Name",
  "description": "Caption text with #tags and @mentions",
  "hashtags": ["tags"],
  "mentions": ["mentions"],
  "likesCount": 3450,
  "likesDisplay": "3.4k",
  "commentsCount": 120,
  "commentsDisplay": "120",
  "videoViewCount": 25000,
  "viewsDisplay": "25k",
  "upload_date_iso": "2025-10-01T12:34:56Z",
  "upload_date": "1st October 2025",
  "upload_time_ago": "1 Month Ago",
  "duration_seconds": 34,
  "duration_display": "34 Seconds",
  "duration_full": {
    "in_seconds": "34 Seconds",
    "in_minutes": "0 Minutes 34 Seconds",
    "in_hours": "0 Hours 0 Minutes 34 Seconds"
  },
  "duration_summary": "⏱ 34s | 0m 34s | 0h 0m 34s",
  "duration_decimal_hours": 0.0094,
  "duration_decimal_minutes": 0.57,
  "duration": 34,
  "resolution": "1920x1080",
  "resolution_detail": "Full HD (1080p)",
  "thumbnail_url": "https://.../thumb.jpg",
  "download_links_summary": { "available": { "merged_video": true } },
  "randomExtraInfo": { "scrapeBatch": "Reel-Set-07", "regionCode": "US", "verifiedStatus": "Creator" }
}

Download mode example (download attempted & merged) — includes duration fields and download metadata

{
  "original_url": "https://www.instagram.com/reel/ABC123/",
  "title": "Video title or null",
  "uploader": "uploader_name",
  "duration": 34,
  "duration_seconds": 34,
  "duration_display": "34 Seconds",
  "duration_full": {
    "in_seconds": "34 Seconds",
    "in_minutes": "0 Minutes 34 Seconds",
    "in_hours": "0 Hours 0 Minutes 34 Seconds"
  },
  "duration_summary": "⏱ 34s | 0m 34s | 0h 0m 34s",
  "duration_decimal_hours": 0.0094,
  "duration_decimal_minutes": 0.57,
  "formats_count": 8,
  "requested_resolution": "1080p",
  "download_links": {
    "merged_video": "https://cdn.example/path/merged.mp4",
    "video_without_audio": null,
    "audio": null
  },
  "downloaded_file": "Video_Title.mp4",
  "merged_file": "Video_Title_merged.mp4",
  "download_links_summary": { "available": { "merged_video": true } }
}

Notes: duration, duration_seconds, duration_display, duration_full, duration_summary, duration_decimal_hours, and duration_decimal_minutes are populated where available — both in scrape and download flows.

---

🔑 Environment Variables & Secrets

• APIFY_TOKEN — use Console secrets or apify-client token placeholder: <APIFY_TOKEN>.
• HTTP_PROXY / HTTPS_PROXY — for custom proxy usage: http://<PROXY_USER:PASS@HOST:PORT> (store as secret).
• cookie_file — reference to a secret input containing cookies (if needed for access-restricted content).

---

▶️ How to Run (detailed)

Console (recommended)

1. Open Actor in Apify Console.
2. Input: paste or upload input.example.json content.
3. (Optional) Configure proxy in the Proxy settings or include proxyConfiguration in input.
4. Click Run and monitor Logs.
5. Download results from Dataset or Key-Value store (OUTPUT).

CLI

$apify run --input input.example.json

API — call actor via apify-client as shown earlier, then fetch dataset by id or read the KVS key OUTPUT.

---

⏰ Scheduling & Webhooks

• Use the Console Schedule tab to run regularly (cron-like UI).
• Configure Webhooks in Console to receive a run-complete event; use payload run IDs to fetch dataset/KVS outputs.

---

🕾️ Logs & Troubleshooting

Where to look

• Console → Run → Logs. Set diagnostic: true for verbose traces.

Common issues & quick fixes

• No startUrls provided: add startUrls.
• Rate limit / access errors: enable platform proxy or supply cookie secrets; set preferred_proxy_type: "residential".
• Downloads failing: ensure download: true; check download_links summary, and verify merge_if_ffmpeg only if ffmpeg is available.

---

🔒 Permissions & Storage Notes

• Output stored in the Dataset and Key-Value store key OUTPUT.
• Files created during downloads live in the Actor container; persist required files to Dataset or KVS if needed.
• The Actor hides raw media links by default to reduce accidental public sharing — toggle via hide_media_links.

---

🔟 Changelog / Versioning

• v1.0.0 — Production-ready: metadata extraction, robust HTML fallback, proxy-aware extraction, safe defaults.

---

🖌 Notes / TODOs

• TODO: confirm output schema — some fields are inferred from runtime behavior (e.g. formats, raw_formats, downloaded_file).
• TODO: add hero GIF/screenshots for the README (improves conversion). Provide images to embed in the README.

---

🌍 Proxy Configuration

This Actor supports platform proxy configuration and custom proxies.

Enable Apify Proxy (Console)

• In Console, define proxyConfiguration in the run input or use the built-in Proxy UI. Actor will create and use sessionized proxy URLs automatically when configured.

Custom proxy example (env vars)

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

Security note

• Always store proxy credentials as Console secrets — never paste them directly into public input.
• TODO: Consider proxy rotation for large-scale scraping runs (use session IDs or platform rotation).

---

📚 References (official Apify docs)

1. Apify Actors — README guidelines.
2. Apify Input/Output schema documentation.
3. Apify CLI & API (apify-client) docs.

---

🤔 What I inferred from main.py

• Accepts startUrls and mode (scrape|download|both).
• Performs metadata extraction first; falls back to HTML metadata scraping on access/rate failures.
• Attempts best-effort download link extraction and optional downloads/merges if requested.
• Creates or uses proxy configuration; sessionizes proxy URLs per URL when platform proxy is enabled.
• Default behavior hides raw media URLs (hide_media_links: true) while preserving thumbnails by default.

---

—— Files included (save in repo)

• README.md — this document.
• input.example.json — copy the JSON from the Inputs section above.
• CONFIG.md — optional local notes (see below).

---

CONFIG.md (optional advanced config)

• Use Console Proxy UI or include a proxyConfiguration object in input.
• For custom proxies, set HTTP_PROXY / HTTPS_PROXY to http://<PROXY_USER:PASS@HOST:PORT>.
• Keep cookies and tokens in Console secrets and reference them via cookie_file or secret input fields.
• TODO: provide recommended rate limits and backoff tuning for bulk runs.

---

This README was produced to be Console-ready: short, outcome-focused, and safe by default. Run a quick test to validate exact output fields for your data pipeline.