Social Scraping

Social Media Scraping with StableSocial

Scrape profiles, posts, comments, followers, and search across TikTok, Instagram, Facebook, and Reddit. All endpoints cost $0.06 per call.

Setup

See rules/getting-started.md for installation and wallet setup.

Notes

Use npx agentcash@latest fetch for paid POST triggers. Use npx agentcash@latest fetch for free GET polling.

IMPORTANT: Use exact endpoint paths from the Quick Reference tables below. All paths include a platform prefix (e.g. https://stablesocial.dev/api/tiktok/...).

How It Works: Async Two-Step Flow

Every request follows a trigger-then-poll pattern:

Step 1: Trigger (paid, $0.06)

npx agentcash@latest fetch https://stablesocial.dev/api/instagram/profile -m POST -b '{"handle": "natgeo"}'

Returns 202 Accepted with a JWT token:

{"token": "eyJhbGciOiJIUzI1NiIs..."}

Step 2: Poll (free)

npx agentcash@latest fetch "https://stablesocial.dev/api/jobs?token=eyJhbGciOiJIUzI1NiIs..."

• {"status": "pending"} — poll again in 3-5 seconds
• {"status": "finished", "data": {...}} — data is ready
• {"status": "failed", "error": "..."} — collection failed (not charged)

Tokens expire after 30 minutes. Jobs typically finish in 5-60 seconds.

Quick Reference — TikTok

Input: {"handle": "username"} for profile/posts/followers. {"query": "keyword"} for search.

Quick Reference — Instagram

Input: {"handle": "username"} for profile/posts/followers. {"query": "keyword"} for search.

Quick Reference — Facebook

Input: {"handle": "username"} or {"profile_id": "id"} for profile. {"query": "keyword"} for search.

Quick Reference — Reddit

Input: {"post_id": "id"} for post details. {"query": "keyword"} for search. {"subreddit": "name"} for subreddit.

Data Dependencies

Some endpoints require a prior collection. For example, to get followers you must first trigger the profile:

# 1. Trigger profile collection
npx agentcash@latest fetch https://stablesocial.dev/api/instagram/profile -m POST -b '{"handle": "natgeo"}'
# Poll until finished...

# 2. Now fetch followers (depends on profile)
npx agentcash@latest fetch https://stablesocial.dev/api/instagram/followers -m POST -b '{"handle": "natgeo"}'
# Poll until finished...

Pagination

When results are paginated, the response includes page_info.has_next_page and a cursor. Pass the cursor to fetch the next page (each page is a new paid POST):

npx agentcash@latest fetch https://stablesocial.dev/api/tiktok/followers -m POST -b '{"handle": "username", "cursor": "abc123"}'

Key Parameters

• handle / profile_id — target account
• max_page_size — results per page (default varies, max 100)
• max_followers — how many followers to collect (default 500)
• max_posts / max_results — item limits (default 50)
• cursor — pagination cursor from previous response
• order_by — sort order: date_desc, date_asc, id_desc

Workflows

Profile Deep Dive

• [ ] (Optional) Check balance: npx agentcash@latest balance
• [ ] Trigger profile collection
• [ ] Poll until finished
• [ ] Trigger posts collection
• [ ] Poll until finished
• [ ] Optionally fetch comments, followers

Cross-Platform Search

• [ ] Search same keyword across multiple platforms
• [ ] Compare results and synthesize findings

npx agentcash@latest fetch https://stablesocial.dev/api/instagram/search -m POST -b '{"query": "brand name"}'
npx agentcash@latest fetch https://stablesocial.dev/api/tiktok/search -m POST -b '{"query": "brand name"}'
npx agentcash@latest fetch https://stablesocial.dev/api/reddit/search -m POST -b '{"query": "brand name"}'

Influencer Analysis

• [ ] Get profile on target platform
• [ ] Fetch recent posts with engagement
• [ ] Get follower list for audience analysis
• [ ] Check comments for sentiment

Competitive Intelligence

• [ ] Search for competitor on target platform
• [ ] Get competitor posts and engagement
• [ ] Monitor competitor mentions across platforms
• [ ] Analyze audience sentiment via comments

npx agentcash@latest fetch https://stablesocial.dev/api/instagram/profile -m POST -b '{"handle": "competitor"}'
npx agentcash@latest fetch https://stablesocial.dev/api/reddit/search -m POST -b '{"query": "competitor name"}'

Cost Estimation

All endpoints are $0.06 per trigger call. Polling is free.

vs social-intelligence Skill

The social-intelligence skill uses Reddit (stableenrich.dev). Use it for quick Reddit post lookups and discussions.

Use social-scraping (this skill) when you need:

• TikTok, Instagram, Facebook, or Reddit data (beyond basic Reddit search)
• Profiles, followers, following — not just search
• Comments, replies, reactions on posts
• Cross-platform research

Getting Started

Setup

1. Install the agentcash CLI:

   npm install -g agentcash

2. Check wallet:

   npx agentcash@latest balance

3. Fund wallet (if needed):

• Redeem invite: npx agentcash@latest redeem YOUR_CODE
• Or run npx agentcash@latest accounts to get Base or Solana deposit links and wallet addresses

Troubleshooting

Pricing Reference

All StableSocial endpoints cost $0.06 per call (paid POST trigger). Polling is free.