Facebook Video Play Count Scraper — Apify Actor

An Apify Actor that extracts the exact play_count for Facebook video / reel / watch URLs, using Apify datacenter proxies for IP rotation.

It is a port of the original local CLI scraper (facebook_playcount_scraper.py) to the Apify platform, so the detection logic (video-id extraction + HTML parsing) is unchanged.

What it does

1. Takes a list of Facebook URLs (via startUrls or a pasted urlsText block).
2. Extracts the numeric video id from each URL (?v=, /videos/…, /reel/…, /watch/…).
3. Reel URLs are auto-converted before scraping: /reel/{id} → https://www.facebook.com/watch/?v={id}. Watch URLs are used as-is.
4. Fetches the page HTML (optionally through Apify proxy), rotating the IP on every retry.
5. Parses the exact play_count for the target video id from the embedded JSON payloads.
6. Pushes one record per URL to the actor's default dataset.

Output record shape

{
    "url": "https://www.facebook.com/watch/?v=1234567890",
    "video_id": "1234567890",
    "play_count": 482311,
    "status": "ok"
}

status is one of:

• ok — play count found.
• invalid_video_id — URL did not contain a recognisable video id.
• play_count_not_found — page fetched, but no matching play count in HTML.
• request_failed: … — all retries failed. The suffix indicates the last error (e.g. http_429, timeout, request_failed: ConnectError).

Input

Field	Type	Default	Description
startUrls	array of {url}	—	Facebook URLs to scrape.
urlsText	string	—	Alternative to startUrls, one URL per line.
maxConcurrency	int	12	Parallel fetches.
requestTimeoutSecs	int	20	Per-request HTTP timeout.
maxRetriesPerUrl	int	3	Retries per URL, each with a fresh proxy IP.
useProxy	bool	true	Toggle proxy usage. Set false to run with no proxy (direct actor IP).
proxyConfiguration	object	{ useApifyProxy: true, apifyProxyGroups: [] }	Apify proxy config (ignored when useProxy is false).

Example input lives at ./.actor/input.example.json.

IP rotation

The actor calls Actor.create_proxy_configuration(actor_proxy_input=…) and then requests a new proxy URL per attempt with a unique session_id, so every retry is guaranteed to go through a different upstream Apify datacenter IP:

proxy_url = await proxy_configuration.new_url(
    session_id=f"fb_{abs(hash(url))}_{attempt}"
)

That session id is also what Apify uses to pin a given IP — by bumping the attempt counter, we explicitly break stickiness after a failure, which is the usual pattern for recovering from rate-limits/soft-blocks on datacenter proxies.

If you want residential proxies instead, edit the input and pass:

"proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
}

Local development

Requires Python 3.11 and the Apify CLI.

# from the project root
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# install Apify CLI (one-time, via npm)
npm install -g apify-cli

# run the actor locally using the example input
apify run --purge --input-file=.actor/input.example.json

Results land in storage/datasets/default/.

Deploy to the Apify platform

apify login        # paste your Apify API token
apify push         # builds the Docker image and pushes the actor

apify push uses .actor/actor.json + .actor/Dockerfile to build the actor on Apify, and .actor/input_schema.json to render the input form in the Apify Console.

After the push you can either:

• Run it from the Apify Console UI.

• Trigger it from the API:

  curl -X POST "https://api.apify.com/v2/acts/<USERNAME>~facebook-playcount-scraper/runs?token=$APIFY_TOKEN" \
       -H "Content-Type: application/json" \
       -d @.actor/input.example.json
  

Project layout

.
├── .actor/
│   ├── actor.json            # actor metadata + dataset view
│   ├── Dockerfile            # build config (apify/actor-python:3.11)
│   ├── input_schema.json     # UI / API input schema
│   └── input.example.json    # sample input for `apify run`
├── src/
│   ├── __main__.py           # `python -m src` entrypoint
│   ├── main.py               # Apify actor logic + proxy rotation
│   └── parser.py             # video-id + play_count extraction
├── facebook_playcount_scraper.py  # original standalone CLI (kept for reference)
├── requirements.txt
├── .dockerignore
├── .gitignore
└── README.md

Push to GitHub

git init
git add .
git commit -m "Apify actor: facebook play count scraper with DATACENTER proxy rotation"
git branch -M main
git remote add origin https://github.com/shanskarBansal/facebook-playcount-scraper.git
git push -u origin main