Apify Runner

Run any Apify Actor to scrape web data (Instagram, TikTok, Reddit, Twitter, etc). Handles Actor discovery, quality filtering, probe testing, batched execution, and result collection. Use when user asks to scrape/crawl/extract data from websites or social media platforms, or mentions Apify directly.

Apify Skill

Run any Apify Actor through a standardized workflow: search → validate → execute → collect results.

Prerequisites

• APIFY_TOKEN env var, or a config.json with tokens (copy config.json.example)
• Python 3 with requests installed

Workflow

Step 1: Parse User Intent

Extract from the user's request:

• Platform/target (Instagram, TikTok, Reddit, etc.)
• What to scrape (posts, profiles, hashtags, comments, etc.)
• Targets (URLs, usernames, keywords)
• Quantity/filters (how many, time range, min likes, etc.)

Step 2: Select Token

If user specifies a token name or the task maps to a specific account, use that. Otherwise use default.

Token can be provided via:

1. --token flag (highest priority)
2. config.json tokens map (by --token-name)
3. APIFY_TOKEN env var (fallback)

Step 3: Search & Select Actor

Run the search script:

python3 scripts/search_actor.py "instagram scraper" --top 3

Output: ranked candidates with score, success rate, rating, pricing model.

Quality filters (built into script):

• notice = NONE (not deprecated)
• 30-day success rate ≥ 95%
• 30-day runs ≥ 1,000
• User rating ≥ 4.0

Pick the top-ranked candidate. If user has a preference or prior experience with a specific Actor, skip search.

Step 4: Get Actor Schema & Build run_input

Fetch the Actor's documentation:

web_fetch https://apify.com/{actor_id}.md

Read the input schema section. Construct run_input JSON based on:

• The Actor's required/optional fields
• The user's targets and filters
• Sensible defaults from the documentation

Do NOT ask the user to write JSON. Build it from their natural language request.

Step 5: Probe Test (Top 1 → Top 2 → Top 3 fallback)

Test with minimal input before committing to full run:

python3 scripts/apify_runner.py {actor_id} \
  --input '{...}' \
  --token {token} \
  --probe-only \
  --list-key {key}

The probe automatically uses the first 2 items from the list field.

Checks:

• Run starts successfully (no permission/billing errors)
• Run completes (no timeout/crash)
• Returns non-empty data

If probe fails → try next candidate Actor. If all 3 fail → report to user with Actor URLs for manual activation.

Step 6: Full Execution

python3 scripts/apify_runner.py {actor_id} \
  --input '{...}' \
  --token {token} \
  --output /path/to/results.json \
  --list-key {key} \
  --batch-size 50 \
  --probe

Key flags:

Flag	Purpose	Default
--list-key	Field in run_input containing the list to batch	None (no batching)
--batch-size	Items per batch	50
--timeout	Per-batch timeout (seconds)	600
--probe	Run probe before full execution	Off
--output	Save results to JSON file	Stdout
--config	Path to config.json for token lookup	None
--token-name	Which token to use from config	"default"

Batching rules:

• ≤ batch-size items → single run
• > batch-size items → auto-split, 3s pause between batches
• Each batch has independent timeout (default 10 min)

Step 7: Return Results

• Report total items collected
• Save raw JSON to specified output path
• Summarize key stats (items count, batches, any failures)
• Let the caller handle filtering/reporting/delivery

Common Actor Patterns

Platform	Typical Actor	list_key	Example input
Instagram	apify/instagram-scraper	directUrls	{"directUrls": ["https://instagram.com/user/"], "resultsType": "posts", "resultsLimit": 3}
TikTok	clockworks/tiktok-scraper	hashtags	{"hashtags": ["cooking"], "resultsPerPage": 50}
Reddit	trudax/reddit-scraper-lite	startUrls	{"startUrls": [{"url": "https://reddit.com/r/cooking/top/?t=month"}], "maxItems": 30}
Twitter	apidojo/tweet-scraper	—	Check .md for current schema

These are starting points. Always verify with the Actor's .md page for current schema.