🌟 Instagram Reels Actor — Instant Reels metadata & media extractor

[] [] []

One-liner: Extract metadata, download media, and store Instagram Reels safely — plug-and-play on Apify Console, results delivered to Dataset & Key-Value store in seconds.

---

📖 Short summary

Run this Actor to instantly fetch rich metadata and optional video files for one or more Instagram Reels URLs. Designed for production runs, privacy-safe storage, and fast integration with downstream pipelines.

---

💡 Use cases / When to use

• Bulk-extract Reels metadata (title, uploader, duration, formats, tags) for analytics.
• Download and store Reel video files into Apify Key-Value Store for processing.
• Enrich content catalogs with human-friendly fields (views, duration display, upload time-ago).
• Build monitoring or archiving workflows for selected Reels.

---

⚡ Quick Start (Console — one-click)

1. Open the Actor in Apify Console.
2. Paste a JSON input (see example below) into the Input field.
3. Click Run — results appear in Dataset and a JSON snapshot is saved to Key-Value store.

Hero screenshot (replace with your own GIF/screenshot for best conversion)

---

⚙️ Quick Start (CLI + API)

CLI (one-liner)

apify run --actor <username/actor-name> --token <APIFY_TOKEN>

Python (apify-client) — compact example

from apify_client import ApifyClient
client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("<username/actor-name>").call(run_input={
    "startUrls": ["https://www.instagram.com/reel/EXAMPLE/"],
    "desired_resolution": "1080p",
    "download": True
})
print("Run started:", run["id"])  # poll run for completion

---

📝 Inputs (fields & example)

Console JSON input example (also available as input.example.json in the canvas)

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

Schema (human-readable)

• startUrls — array of Reel URLs to process (required)
• desired_resolution — preferred video resolution (string, e.g. "1080p")
• download — whether to download media files to Key-Value Store (boolean)
• merge_if_ffmpeg — attempt audio/video merge if system tool available (boolean)
• cookie_file — optional path or cookie-file identifier for authenticated requests (string/null)
• proxyConfiguration — optional Apify-style proxy configuration object (object)

---

⚙️ Configuration (quick reference)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	["https://www.instagram.com/reel/CODE12345/"]	One or more Reel URLs — must include /reel/
desired_resolution	string	⚙️ Optional	"1080p"	"720p"	Preferred download resolution — actor picks best match
download	boolean	⚙️ Optional	true	true	When enabled, video files are uploaded to Key-Value Store
merge_if_ffmpeg	boolean	⚙️ Optional	true	true	If enabled and system merge tool available, audio+video may be merged
cookie_file	string/null	⚙️ Optional	null	"cookies.txt"	For private or session-authenticated content
proxyConfiguration	object	⚙️ Optional	{useApifyProxy:true}	{"useApifyProxy":true}	Configure in Console Input or use Apify Proxy UI

Console tip: Paste values into the Input editor or use the generated input schema to render fields.

---

📄 Outputs (Dataset & Key-Value examples)

This Actor emits rich, structured items to the Dataset and uploads media files to Key-Value Store when download: true.

Fields (30 output types)

Below are the 30 most important output fields you will commonly see in each dataset item. Types are shown in parentheses and short notes follow.

1. original_url (string) — input Reel URL.
2. id (string|int) — Reel unique id.
3. title (string) — best-effort title or caption excerpt.
4. ownerFullName (string|null) — creator full name when available.
5. ownerUsername (string) — creator username.
6. ownerId (string|int|null) — numeric owner id when available.
7. description (string|null) — caption text.
8. likesCount (int|null) — numeric likes count.
9. likesDisplay (string|null) — human friendly likes (e.g. "1.2k").
10. commentsCount (int|null) — numeric comments count.
11. commentsDisplay (string|null) — human friendly comments (e.g. "200").
12. videoViewCount (int|null) — views for video posts (if available).
13. viewsDisplay (string|null) — human friendly views representation.
14. upload_date_iso (string|null) — original ISO upload timestamp.
15. upload_date (string|null) — pretty upload date (e.g. "5th June 2024").
16. upload_time_ago (string|null) — relative time (e.g. "5 Months Ago").
17. duration_seconds (number|null) — canonical duration in seconds.
18. duration_display (string|null) — friendly duration label.
19. duration_full (object|null) — expanded durations (in_seconds, in_minutes, in_hours).
20. duration_summary (string|null) — compact summary (e.g. "⏱ 32s | 0m 32s | 0h 0m 32s").
21. resolution (string|null) — raw resolution (e.g. "1080x1920").
22. resolution_detail (string|null) — labeled resolution (e.g. "Full HD (1080p)").
23. type (string) — content type (e.g. "GraphVideo" or "GraphImage").
24. hashtags (array) — list of extracted hashtags (strings).
25. mentions (array) — list of mentioned usernames (strings).
26. formats (array) — available format objects (type,url,duration,width,height...).
27. download_link (object|null) — downloader summary: requested_resolution, formats_count, download_links map.
28. formats_count (int) — number of formats discovered by extractor.
29. downloaded_kv_key (string|null) — Key-Value Store key where the raw downloaded file was saved (if any).
30. video_kv_key (string|null) — convenience alias pointing to the same KV key for video files.

Tip: some runs include extra fields like scrape_error or raw_info when extraction or scraping encounters issues; these appear only for error debugging.

Example dataset item (condensed — showing the 30 fields)

{
  "original_url": "https://www.instagram.com/reel/CODE12345/",
  "id": "1234567890",
  "title": "Short caption excerpt",
  "ownerFullName": "Creator Name",
  "ownerUsername": "creator_handle",
  "ownerId": "987654321",
  "description": "Caption text...",
  "likesCount": 1250,
  "likesDisplay": "1.2k",
  "commentsCount": 45,
  "commentsDisplay": "45",
  "videoViewCount": 5400,
  "viewsDisplay": "5.4k",
  "upload_date_iso": "2024-06-05T12:34:56Z",
  "upload_date": "5th June 2024",
  "upload_time_ago": "5 Months Ago",
  "duration_seconds": 32.0,
  "duration_display": "0 Minutes 32 Seconds",
  "duration_full": {"in_seconds":"32 Seconds","in_minutes":"0 Minutes 32 Seconds","in_hours":"0 Hours 0 Minutes 32 Seconds"},
  "duration_summary": "⏱ 32s | 0m 32s | 0h 0m 32s",
  "resolution": "1080x1920",
  "resolution_detail": "Full HD (1080p)",
  "type": "GraphVideo",
  "hashtags": ["funny","trending"],
  "mentions": ["friend1"],
  "formats": [{"type":"video","url":"https://...","duration":32}],
  "download_link": {"requested_resolution":"1080p","formats_count":6,"download_links":{"merged_video":"https://...mp4"}},
  "formats_count": 6,
  "downloaded_kv_key": "videos/reel_1234567890_merged.mp4",
  "video_kv_key": "videos/reel_1234567890_merged.mp4"
}

---

🔑 Environment Variables & Secrets & Secrets

• <APIFY_TOKEN> — use in CLI or apify-client (never store plaintext in code).
• HTTP_PROXY / HTTPS_PROXY — only needed for custom proxy targets (see proxy section).
• IG_USER / IG_PASS — optional: provide console secrets if you need authenticated scraping for private content.

Always store credentials using Apify Console Secrets (do not paste plaintext into actor input).

---

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

Console (recommended)

1. Open Actor page in Apify Console.
2. Paste JSON input (see input.example.json).
3. Click Run. Monitor Dataset & Key-Value Store.

CLI

apify run --actor <username/actor-name> --token <APIFY_TOKEN>

API (apify-client) — see Quick Start snippet above.

---

⏰ Scheduling & Webhooks

• Schedule runs using the Console Scheduler tab — pick interval or CRON expression.
• Use Webhooks in run settings to POST results to your endpoint after completion.
• For large batch schedules, enable proxy rotation and throttle to respect rate limits.

---

🕾 Logs & Troubleshooting

• Logs are available in the Console Run page — check stdout and stderr for step-level details.

• Common issues & fixes:

  • No startUrls provided — ensure startUrls array is not empty.
  • No valid Reel URLs found — provide URLs containing /reel/.
  • Download failed — ensure proxy is configured or cookie_file is provided for private content; check quota.
  • Merge skipped — local merging requires a system merge tool to be available; fallback to video-only is supported.

---

🔒 Permissions & Storage Notes

• Uses Dataset for structured items and Key-Value Store for media files.
• This Actor follows privacy-safe defaults: do not store credentials in plaintext and use Console Secrets.
• Designed to be safe for production workflows; respect target site ToS and rate limits.

---

🔟 Changelog / Versioning (short)

• 1.0.0 — Initial public release: metadata extraction, optional downloads, KV storage, dataset push.

---

🖌 Notes / TODOs

• TODO: confirm exact output schema — common fields inferred from runtime behavior.
• TODO: add demo GIF/screenshots (replace hero image for best conversion).

---

🌍 Proxy Configuration

Enable Apify Proxy (quick) — In Apify Console, enable Apify Proxy in the Run settings or input proxyConfiguration: {"useApifyProxy": true}.

Custom proxy example

• Environment-style variables (Console secret recommended):

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

• Input example (custom proxy object):

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

Notes & Security

• Store proxy credentials as Console secrets — never paste credentials into the public Input field.
• TODO: Consider proxy rotation for large-scale scraping to reduce rate-limit risk and improve resilience.

---

📚 References

• How to create an Actor README — Apify Academy
• Actor input schema — Apify Platform docs
• Apify API Client (Python) — Apify docs

---

🤔 What I inferred from main.py

• The Actor accepts a startUrls array and processes only URLs containing /reel/.
• The Actor performs remote media extraction and optional file download (network activity present).
• Downloads (when enabled) are stored in Key-Value Store under a videos/ prefix and each dataset item includes the KV key.
• Optional authenticated or cookie-based scraping is supported via an input cookie_file and optional IG credentials as secrets.
• The Actor will attempt to use an available system merge tool for audio/video merging if requested; otherwise it falls back to video-only.

---

Why this Actor — short benefits

• Instant insights: get friendly metadata (views, likes, time-ago) without parsing raw payloads.
• Secure by design: uses Console secrets and KV/Dataset; no secrets in output.
• Production-ready: built to run at scale with proxy support and retry/backoff behavior.

Run this Actor on Apify Console — get instant results in seconds.

---

---

input.example.json

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

CONFIG.md

# CONFIG: Advanced tips & proxy notes

1) Apify Proxy
- Enable from Run settings or set "proxyConfiguration": {"useApifyProxy": true} in input.

2) Custom proxy
- Provide proxy URLs in the proxyConfiguration object or set HTTP_PROXY/HTTPS_PROXY as secrets.
- Example: HTTP_PROXY="http://<PROXY_USER:PASS@HOST:PORT>"

3) Authenticated scraping
- For private content, set IG_USER and IG_PASS as Console Secrets and provide cookie_file input if needed.

4) Merge tool
- For audio/video merging, ensure a system merge tool is available in the runtime. If not present, the Actor falls back to video-only.

5) TODO
- Consider proxy rotation for large-scale scraping to improve resilience.