Generating Leads

Scrape leads from multiple platforms using Apify Actors.

Prerequisites

• .env file with APIFY_TOKEN
• Python 3.9+ and uv

Workflow

Copy this checklist and track progress:

Task Progress:
- [ ] Step 1: Determine lead source (select Actor)
- [ ] Step 2: Read Actor schema from reference docs
- [ ] Step 3: Ask user preferences (format, filename)
- [ ] Step 4: Run the lead finder script
- [ ] Step 5: Summarize results

Step 1: Determine Lead Source

Select the appropriate Actor based on user needs:

User Need	Actor ID	Best For	Reference Doc
Local businesses	compass/crawler-google-places	Restaurants, gyms, shops	Schema
Contact enrichment	vdrmota/contact-info-scraper	Emails, phones from URLs	Schema
Instagram profiles	apify/instagram-profile-scraper	Influencer discovery	Schema
Instagram posts/comments	apify/instagram-scraper	Posts, comments, hashtags, places	Schema
Instagram search	apify/instagram-search-scraper	Places, users, hashtags discovery	Schema
TikTok videos/hashtags	clockworks/tiktok-scraper	Comprehensive TikTok data extraction	Schema
TikTok hashtags/profiles	clockworks/free-tiktok-scraper	Free TikTok data extractor	Schema
TikTok user search	clockworks/tiktok-user-search-scraper	Find users by keywords	Schema
TikTok profiles	clockworks/tiktok-profile-scraper	Creator outreach	Schema
TikTok followers/following	clockworks/tiktok-followers-scraper	Audience analysis, segmentation	Schema
Facebook pages	apify/facebook-pages-scraper	Business contacts	Schema
Facebook page contacts	apify/facebook-page-contact-information	Extract emails, phones, addresses	Schema
Facebook groups	apify/facebook-groups-scraper	Buying intent signals	Schema
Facebook events	apify/facebook-events-scraper	Event networking, partnerships	Schema
Google Search	apify/google-search-scraper	Broad lead discovery	Schema
YouTube channels	streamers/youtube-scraper	Creator partnerships	Schema
Google Maps emails	poidata/google-maps-email-extractor	Direct email extraction	Schema

Step 2: Read Actor Schema

Read the corresponding reference doc from the table above to understand:

• Required and optional input parameters
• Output fields available
• Actor-specific requirements

Step 3: Ask User Preferences

Before running, ask:

1. Output format:
   • Quick answer - Display top 5 results in chat (no file saved)
   • CSV (all data) - Full export with all fields
   • CSV (basic fields) - Export with essential fields only
   • JSON (all data) - Full export in JSON format
2. Output filename (if file output selected): Suggest descriptive name based on search

Step 4: Run the Script

Quick answer (display in chat, no file):

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT'

CSV (all data):

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output OUTPUT_FILE.csv \
  --format csv

CSV (basic fields):

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output OUTPUT_FILE.csv \
  --format csv \
  --fields basic

JSON (all data):

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output OUTPUT_FILE.json \
  --format json

The script handles:

• Loading APIFY_TOKEN from .env
• Starting and polling the Actor run
• Downloading results in requested format (or displaying in chat)
• Reporting record count and file size

Step 5: Summarize Results

After completion, report:

• Number of leads found
• File location
• Key fields available
• Suggested next steps (filtering, enrichment)

Quick Examples

Quick answer - display top 5 in chat:

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "compass/crawler-google-places" \
  --input '{"searchStringsArray": ["coffee shops"], "locationQuery": "Seattle, USA", "maxCrawledPlacesPerSearch": 50}'

Google Maps - CSV with basic fields:

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "compass/crawler-google-places" \
  --input '{"searchStringsArray": ["coffee shops"], "locationQuery": "Seattle, USA", "maxCrawledPlacesPerSearch": 50}' \
  --output coffee-shops-seattle.csv \
  --format csv \
  --fields basic

Contact enrichment - full JSON export:

uv run --with python-dotenv --with requests \
  ${CLAUDE_PLUGIN_ROOT}/skills/generating-leads/reference/scripts/run_actor.py \
  --actor "vdrmota/contact-info-scraper" \
  --input '{"startUrls": [{"url": "https://example.com"}], "maxRequestsPerStartUrl": 20}' \
  --output contacts.json \
  --format json

See reference/workflows.md for detailed step-by-step guides for each use case.

Error Handling

Error	Solution
APIFY_TOKEN not found	Ask user to create .env with APIFY_TOKEN=your_token
Actor not found	Check Actor ID spelling
Run FAILED	Ask user to check Apify console link in error output
Timeout	Reduce input size or increase --timeout