🌟 Instagram Reels Actor — Fast Metadata Scraper and Downloader

Instantly fetch metadata for Instagram Reels — production-ready, privacy-safe, and built for high-volume scraping with download links.

---

📖 One‑line summary

Fetch clean, enriched metadata from Instagram Reels (upload date, views, likes, resolution, and fully expanded duration formats) so you can analyze, index, or display results without handling media files.

---

💡 Use cases / When to use

• Build analytics dashboards (views, likes, engagement) for Reels at scale.
• Populate a content index or CMS with rich metadata (timestamps, resolution, captions).
• Audit or monitor creators and content trends across many Reels.
• Quick ad-hoc or recurring scraping runs for market research or archiving.

---

⚡ Quick Start — Console (one-click)

1. Open this Actor in Apify Console.
2. Paste a list of Reels into Input (see example below).
3. Click Run — results appear in the Dataset within seconds.

---

⚙️ Quick Start — CLI & API

CLI (apify-cli)

$apify run --actor <OWNER>/<ACTOR_NAME> --input input.example.json

Python (apify-client)

from apify_client import ApifyClient
client = ApifyClient('<APIFY_TOKEN>')
run = client.actor_runs.run('<OWNER>/<ACTOR_NAME>', input={
  "startUrls": ["https://www.instagram.com/reel/SHORTCODE/"],
  "desired_resolution": "1080p"
})
print(run)

---

📝 Inputs (fields & schema)

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

{
  "startUrls": [
    "https://www.instagram.com/reel/SHORTCODE/"
  ],
  "desired_resolution": "1080p",
  "cookie_file": null,
  "concurrency": 3,
  "proxyConfiguration": {"useApifyProxy": true}
}

Schema (inferred)

• startUrls — array of strings or objects with url (required) — list of Reel URLs to scrape.
• desired_resolution — string (optional, default: 1080p) — resolution preference for format selection.
• cookie_file — string (optional) — path or secret name containing cookies (if needed for private content).
• concurrency — integer (optional, default: 3) — how many Reels to process concurrently.
• proxyConfiguration — object (optional) — Apify Proxy or custom proxy settings.

---

⚙️ Configuration (fields, defaults & Console hint)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array	✅ Yes	None	["https://.../reel/SHORTCODE/"]	List of Reels to fetch (or objects with url).
desired_resolution	string	⚙️ Optional	"1080p"	"720p"	Preferred format selection (1080p, 720p, ...).
cookie_file	string	⚙️ Optional	null	"<COOKIE_SECRET_NAME>"	Use when scraping private content; store cookie as secret.
concurrency	integer	⚙️ Optional	3	5	Increase for parallel runs (watch rate-limits).
proxyConfiguration	object	⚙️ Optional	{}	{"useApifyProxy": true}	Enable Apify Proxy or custom proxy settings.

Console tip: Paste the startUrls array into the Input field, tweak desired_resolution, then click Run.

---

📄 Outputs (Dataset / examples)

The Actor writes enriched metadata objects to the Dataset and also saves a copy to key-value storage (full run results). Each output object includes standard fields plus fully expanded duration formats.

Example output object (abridged):

{
  "original_url": "https://www.instagram.com/reel/SHORTCODE/",
  "id": "SHORTCODE",
  "title": null,
  "description": "Caption text...",
  "likesCount": 1234,
  "likesDisplay": "1.2k",
  "commentsCount": 12,
  "commentsDisplay": "12",
  "videoViewCount": 9876,
  "viewsDisplay": "9.9k",
  "upload_date_iso": "2023-05-03T12:34:56Z",
  "upload_date": "3rd May 2023",
  "upload_time_ago": "2 Months Ago",

  "duration_seconds": 125.123,
  "duration": 125.123,
  "duration_display": "2 Minutes 5 Seconds (0.0347 Hours)",
  "duration_full": {
    "in_seconds": "125 Seconds",
    "in_minutes": "2 Minutes 5 Seconds",
    "in_hours": "0 Hours 2 Minutes 5 Seconds"
  },
  "duration_summary": "⏱ 125s | 2m 5s | 0h 2m 5s",
  "duration_decimal_hours": 0.0348,
  "duration_decimal_minutes": 2.09,

  "resolution": "1080x1920",
  "resolution_detail": "Full HD (1080p)",
  "thumbnail_url": "https://...",
  "formats": [ /* format entries (urls + type) */ ],
  "randomExtraInfo": {"scrapeBatch": "Reel-Set-42", "regionCode": "US", ... }
}

All duration keys included: duration_seconds, duration_display, duration_full, duration_summary, duration_decimal_hours, duration_decimal_minutes, and duration (alias for seconds).

---

🔑 Environment variables & secrets

Name	Purpose	Example / Placeholder
<APIFY_TOKEN>	Auth for apify-client (if using API)	<APIFY_TOKEN>
<PROXY_USER:PASS@HOST:PORT>	Custom proxy (if not using Apify Proxy)	<PROXY_USER:PASS@HOST:PORT>
COOKIE_SECRET_NAME	Optional: name of cookie file stored as secret	MY_IG_COOKIES

Security: store tokens and cookies as secrets in Apify Console — do not paste them directly into input JSON.

---

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

1. Console — paste input.example.json and click Run.
2. CLI — apify run --actor <OWNER>/<ACTOR_NAME> --input input.example.json
3. API — use apify-client (see snippet above), pass <APIFY_TOKEN> as your token.

---

⏰ Scheduling & Webhooks

• Scheduling: Use Apify Console scheduling to run daily/hourly. Configure concurrency based on your proxy limits.
• Webhooks: Configure a webhook in Console to receive a callback when a run completes — point to your listener URL.

---

🕾️ Logs & Troubleshooting

• Where to find logs: Console → Run details → Logs.

• Common fixes:

  • No results / timeouts: enable Apify Proxy or increase concurrency cautiously.
  • 403 or blocked: provide a cookie file (stored as a secret) or use Apify Proxy.
  • Malformed input: ensure startUrls contains valid Reel URLs.

---

🔒 Permissions & Storage Notes

• Storage used: Dataset (primary results) and Key-Value store (full run copy). No media files are downloaded or stored.
• Privacy: This Actor returns only public metadata unless you provide cookies for private content. Always store cookies/tokens as secrets.

---

🔟 Changelog / Versioning

• 1.0.0 — Initial public release: fast metadata scraping with enriched duration formatting and upload date parsing.

---

🖌 Notes / TODOs

• TODO: confirm specific cookie file name behavior for private content — inferred from runtime.
• TODO: provide a short demo GIF (3–5s) showing Console run & Dataset result for higher conversions.

---

🌍 Proxy Configuration

This Actor performs network requests. You can run it using the built-in Apify Proxy or supply custom proxies.

Enable Apify Proxy (recommended)

• In Console: open the Run configuration → Proxy → Enable Apify Proxy.

Custom proxy (example)

• Set proxyConfiguration in input or use env vars:

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

Security: store proxy credentials as secrets in Console — do not include them in shared input.

Advanced: TODO: Consider proxy rotation for large-scale scraping.

---

📚 References (official)

• Actor README guidelines — https://docs.apify.com/actors
• Input / Output schema best practices — https://docs.apify.com/actors/input-output
• apify-cli & apify-client usage — https://docs.apify.com/tools

---

🤔 What I inferred from main.py

• The Actor scrapes Instagram Reels metadata (network activity present).
• Inputs: startUrls, desired_resolution, cookie_file, concurrency, proxyConfiguration.
• Outputs: full metadata object including expanded duration fields and upload date parsing.
• No media files are downloaded — this Actor returns URLs and metadata only.

---

✅ Why this Actor (short benefit copy)

• Instant insights: get clean, enriched Reel metadata in seconds.
• Secure by design: no media downloads, secrets remain in Console.
• Production-ready: tuned defaults for reliability and concurrency.
• Plug & play: paste URLs, click Run, get structured output.

---

input.example.json

{
  "startUrls": [
    "https://www.instagram.com/reel/SHORTCODE/"
  ],
  "desired_resolution": "1080p",
  "cookie_file": null,
  "concurrency": 3,
  "proxyConfiguration": {"useApifyProxy": true}
}

CONFIG.md

Quick configuration notes

• Secrets: store <APIFY_TOKEN>, cookie files, and proxy credentials as secrets in Apify Console.
• Proxy: prefer Apify Proxy for scale. For custom proxies, set HTTP_PROXY and HTTPS_PROXY environment variables or fill proxyConfiguration in input.
• Concurrency: keep default 3 for safe runs; increase only if you monitor rate-limits.

---