🌟 Instagram Reels Exporter — Instant Scarpe Reel metadata & download Video

One-liner (hero): Fetch Instagram Reels metadata and download videos to Apify Key-Value Store — production-ready, privacy-safe, and plug‑and‑play.

---

📖 Short summary

Get structured metadata (uploader, captions, tags, views, likes, formatted dates) for Instagram Reels and optionally save video files to Apify Key‑Value Store. Runs on Apify Console with zero setup — results in seconds.

---

💡 Use cases / When to use

• Archiving Reels metadata for analytics or reporting.
• Building a discovery feed from selected Reels URLs.
• Rapidly fetching captions, hashtags, mentions, and friendly metrics for dashboards.
• Batch-downloading Reels for internal review or content moderation (privacy-safe).

---

⚡ Quick Start (Console — one-click)

1. Open the Actor in Apify Console.
2. Paste a JSON input (see input.example.json in this package).
3. Click Run — results stream to Dataset and a JSON snapshot is saved to Key‑Value store.

Microcopy: "Plug & play — runs in seconds. Secure by design."

---

⚙️ Quick Start (CLI + API)

CLI (one-liner)

# Run a public actor from Apify Store:
apify call <owner>/<actor-name> --token <APIFY_TOKEN> --input input.example.json

Python (apify-client) — run & wait for results

from apify_client import ApifyClient

client = ApifyClient('<APIFY_TOKEN>')
run = client.actor('<owner>/<actor-name>').call(run_input={
    "startUrls": ["https://www.instagram.com/reel/EXAMPLE/"]
})
# run contains run metadata; fetch dataset items or Key-Value after completion

Replace <owner>/<actor-name> with your actor ID and <APIFY_TOKEN> with your token. Store tokens as secrets — never inline them.

---

📝 Inputs (fields & schema)

Below is the Console JSON input example (also saved as input.example.json). The actor accepts a JSON object with these fields:

{
  "startUrls": [
    "https://www.instagram.com/reel/CRYSTAL_EXAMPLE/"
  ],
  "desired_resolution": "1080p",
  "download": true,
  "merge_if_ffmpeg": true,
  "cookie_file": null,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

Notes:

• startUrls is required and must contain one or more Instagram Reel URLs (must include /reel/).
• desired_resolution accepts common labels like 1080p, 720p. If the exact resolution is not available the actor picks the nearest available.

---

⚙️ Configuration (friendly table — inferred fields)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	["https://.../reel/EXAMPLE/"]	One or more Reel URLs (must include /reel/).
desired_resolution	string	⚙️ Optional	"1080p"	"720p"	Preferred download resolution; actor selects best match.
download	boolean	⚙️ Optional	true	false	Toggle to download video files to Key‑Value store.
merge_if_ffmpeg	boolean	⚙️ Optional	true	true	If system merger tool present, audio+video streams will be merged.
cookie_file	string	⚙️ Optional	null	"cookies.txt"	Path or Console-secret name for cookies (optional, for private content).
proxyConfiguration	object	⚙️ Optional	{useApifyProxy:true}	{"useApifyProxy": false, "proxyUrls": ["<PROXY_USER:PASS@HOST:PORT>"]}	Use Console proxy or provide custom proxies.

Example Console setup: paste https://www.instagram.com/reel/CRYSTAL_EXAMPLE/ into startUrls, set download to true, then click Run Actor.

TODO: confirm any optional cookie_file format for Console secret references — not explicit in main.py.

---

📄 Outputs (Dataset / Key‑Value examples)

Primary outputs:

• Each run pushes transformed items into the default Dataset (one item per URL).
• A full array snapshot is saved to Key‑Value under OUTPUT (JSON).
• Optional video files saved to Key‑Value under videos/<filename> when download=true.

Example dataset item (shortened):

{
  "original_url": "https://www.instagram.com/reel/CRYSTAL_EXAMPLE/",
  "id": "1234567890",
  "ownerUsername": "creator_name",
  "description": "Short caption text #tag",
  "hashtags": ["tag"],
  "mentions": [],
  "likesCount": 1200,
  "likesDisplay": "1.2k",
  "commentsCount": 45,
  "commentsDisplay": "45",
  "videoViewCount": 32000,
  "viewsDisplay": "32k",
  "upload_date_iso": "2025-01-01T12:00:00Z",
  "upload_date": "1st January 2025",
  "upload_time_ago": "10 Months Ago",
  "formats": [{"type":"video","url":"https://..."}],
  "download_link": {
    "requested_resolution": "1080p",
    "formats_count": 6,
    "download_links": {"merged_video":"https://..."}
  },
  "video_kv_key": "videos/reel_title_merged.mp4"
}

---

🔑 Environment Variables

Store these as Console secrets or in the Actor's environment settings (never in plain text inputs).

• <APIFY_TOKEN> — your Apify API token (used with CLI/API examples).
• <PROXY_USER:PASS@HOST:PORT> — example format for custom proxy credentials.
• IG_USER, IG_PASS — optional Instagram credentials if available (store as secrets). TODO: confirm whether credentials are required for private content.

---

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

Console (recommended)

• Go to the Actor page in Apify Console → Inputs → paste input.example.json → Run.

CLI

• apify call <owner>/<actor-name> --token <APIFY_TOKEN> --input input.example.json

Python apify-client

• See Quick Start example above. After call(), retrieve dataset items or use client.dataset(<datasetId>).list_items() to fetch results.

---

⏰ Scheduling & Webhooks

• Schedule runs in Apify Console under the Scheduling tab (choose cron or interval).
• Add a webhook in Console to POST run metadata or dataset URL to your endpoint after completion.

Microcopy: schedule recurring jobs for continuous monitoring — “set & forget” analytics.

---

🕾️ Logs & Troubleshooting

Where to find logs: Apify Console → Run → Logs.

Common issues & quick fixes

• No startUrls provided — add at least one startUrls entry. (Actor fails fast.)
• Non‑reel URLs skipped — ensure URLs include /reel/ path.
• Download fails or missing — check proxy settings and that system merger tool is available; consider toggling download to false to debug metadata-only flows.
• Permission/401 errors — add IG_USER/IG_PASS as secrets if accessing restricted content.

---

🔒 Permissions & Storage Notes

• Uses Dataset for structured records and Key‑Value Store for snapshots and optional video files.
• Video files saved as videos/<filename> in Key‑Value; keep them private or configure access per your org policies.
• Privacy: do not use this Actor for scraping private or sensitive personal data without legal basis. Actor is designed for privacy-safe public content extraction.

---

🔟 Changelog / Versioning

• v1.0.0 — Initial product-style release: metadata extraction + optional downloads, proxy support, dataset + KV outputs.

---

🖌 Notes / TODOs

• TODO: confirm exact cookie file referencing convention in Apify Console (secret name vs path).
• TODO: add demo GIF/screenshots (high-converting hero visuals improve conversions).

---

🌍 Proxy Configuration

This Actor performs network activity to fetch metadata and download video streams. Proxy usage is recommended for reliability and scale.

Enable Apify Proxy (Console)

• In Inputs, set proxyConfiguration.useApifyProxy = true (default behavior). The Actor will create a Proxy configuration automatically when run.

Custom proxies

• You may provide a custom proxy in proxyConfiguration or via environment variables. Example proxy placeholder:

{"proxyConfiguration": {"proxyUrls": ["<PROXY_USER:PASS@HOST:PORT>"]}}

HTTP(S)_PROXY examples

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

Security note: Store credentials as Console secrets — do not paste credentials in the public input field.

Advanced: TODO: Consider proxy rotation for large‑scale scraping to avoid rate limits.

---

📚 References

• How to create an Actor README (Apify docs). citeturn0search0
• Actor input schema (Apify Platform docs). citeturn0search1
• Apify API Client for Python — examples. citeturn0search3

---

🤔 What I inferred from main.py

• Network activity: Actor fetches Instagram Reel pages and video streams (yes — proxy section included).
• Inputs: startUrls (required), desired_resolution, download, merge_if_ffmpeg, cookie_file, proxyConfiguration.
• Outputs: pushes transformed items to Dataset, saves full results to Key‑Value under key OUTPUT, optionally stores videos under videos/ keys.
• Merging: actor attempts to merge audio+video when a system merger tool is available; merging is optional.
• Authentication: optional IG credentials read from IG_USER / IG_PASS environment variables (secrets recommended).

---

input.example.json

{
  "startUrls": [
    "https://www.instagram.com/reel/CRYSTAL_EXAMPLE/"
  ],
  "desired_resolution": "1080p",
  "download": true,
  "merge_if_ffmpeg": true,
  "cookie_file": null,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

CONFIG.md

Quick config notes

• Place sensitive tokens in Apify Console's Secrets / Environment variables.
• To enable custom proxies, set proxyConfiguration.proxyUrls to an array of your proxies.
• For private content, add IG_USER and IG_PASS as environment variables (Console secrets) and set cookie_file if you have a cookies export.

Example advanced proxy entry

{
  "proxyConfiguration": {
    "useApifyProxy": false,
    "proxyUrls": ["http://<PROXY_USER:PASS@HOST:PORT>"]
  }
}

---