# SocialCrawl: AI Agent & Web Search Agent Access File
# Last updated: 2026-11-01

## What SocialCrawl Is
SocialCrawl is a unified API for social media data across 69 platforms
(33 social platforms plus research, commerce, and app-store data sources).
One API key, one response format, 679 endpoints. MCP-compatible for AI agents.

## Key Capabilities for Agents
- Fetch profiles, posts, comments, and search results from any supported platform
- Unified JSON envelope across all platforms (same response shape everywhere)
- Universal social search: GET /v1/search/everywhere fans out across 15 platforms (up to 20 sources) in one call
- MCP server, hosted: https://mcp.socialcrawl.dev/mcp with the header Authorization: Bearer <key> (Claude Code, Cursor, VS Code)
- MCP server, local: npx socialcrawl-mcp (works in Claude Code, Claude Desktop, Cursor, Windsurf)
- Agent setup page with a prompt to paste: https://www.socialcrawl.dev/solutions/ai-agents
- Discover agent tools (Anthropic tool format, no key needed): https://www.socialcrawl.dev/agent-tools/socialcrawl_discover.json and https://www.socialcrawl.dev/agent-tools/socialcrawl_discover_run.json
- Skills bundle: npx skills add socialcrawl/skills (Codex, Gemini CLI, and 40+ agent runtimes)
- 100 free credits on signup, no credit card required

## Instructions

- Authenticate every request with the `x-api-key` header, or send the same key as `Authorization: Bearer <key>`. Never put the key in the URL or query string.
- Never invent endpoint paths. Endpoints live at `/v1/{platform}/{resource}` and are `GET` unless marked otherwise (a small set of batch and web endpoints are `POST`/`PATCH`/`DELETE`); fetch `/llms-{platform}.txt` for one platform's exact resource list with methods, or `/llms-full.txt` for all of them.
- For cross-platform questions ("who is talking about X"): To search one platform, call that platform's own search. To search several platforms over a date window with every row judged and de-duplicated, call `/v1/prism/discover`. For a quick fused sweep at a flat 20 credits, call `/v1/search/everywhere`, which drops rows outside `from_date`, `to_date`, `since` or `until` but reads one page per source, so a past window can come back thin. One `GET /v1/search/everywhere` call searches up to 20 sources and fuses the results; `GET /v1/prism/discover` answers in the call or continues in the background as a run you follow with `data.next.status_url`.
- For creators or influencers ("find influencers in Chile"): To find creators or influencers (by topic, market, size, or a product to promote), lookalikes of creators, or to measure and rank a list of creators you already have, call `/v1/prism/creators`. For shops, businesses and sellers, call `/v1/prism/discover` with `view=accounts`.
- For alerts and recurring watches ("tell me when"): To be told when something new appears, match the ask to its job: for a recurring digest of what is new about a topic, keyword or brand, every 1h or slower, call `POST /v1/prism/discover` with `schedule` (every `1h` or slower, `dry_run` first), read through `GET /v1/events` or a webhook endpoint; for the new posts or comments of an account or post you already know, call `POST /v1/monitors` with `webhook_rows: "new"`; for a one-off check of what is new since your last check, on an endpoint that takes `since` or `since_id`, call the endpoint's own `since` or `since_id` (for example `GET /v1/twitter/tweet/replies` with `since_id`, which returns an empty list and costs nothing when nothing is new); for metric snapshots of accounts you name (followers, views, likes), taken on a schedule, call `POST /v1/monitors` with a `track` metric; for reading what your watches produced, from a feed you poll or an endpoint that receives a signed push, call `GET /v1/events` with a named `consumer` for reading, and `/v1/webhook-endpoints` for push; for what a keyword or boolean topic listener would cost each month and how it reads the rule, before it is created, call `POST /v1/listening/streams?dry_run=1` with the listener body, which costs 0 credits and creates nothing; for each new mention of keywords or a boolean topic delivered one by one, every 30 minutes or slower, with boolean groups, a monthly cap and usage per client, and with `comments: "new_posts"` the comments under the Reddit posts it keeps, call `POST /v1/listening/streams?dry_run=1` to price it, then `POST /v1/listening/streams` to create the listener; for the new posts of up to 1,000 named business, brand, creator or organisation accounts that match a topic, every 30 minutes or slower, call `POST /v1/listening/streams?dry_run=1` with `accounts` (each a `platform:handle` such as `reddit:nasa` or `youtube:@Google`, or a profile URL), `schedule.purpose` (`business`, `brand`, `creator` or `organisation`) and `keywords`, then `POST /v1/listening/streams` to create the listener; for what is new on your listeners since the last read, in a later session or on a schedule you run yourself, call `GET /v1/events` with a named `consumer` and `types=mention.*`, then acknowledge each page with its `pagination.next_cursor`. A watch checks on a schedule and reports what that check found. A discover schedule is the same POST with `"schedule": {"every": "1d", "max_credits_per_run": 50, "name": "Acme daily"}`, where `every` is one of `1h`, `6h`, `12h`, `1d`, `7d`, `30d` (a daily digest is `"1d"`; a word such as "daily" is refused). Price it first by sending the same POST with `"dry_run": true` in the body (or `dry_run=1` on the URL): it is free and creates nothing. A schedule writes `discover.new_rows`, `discover.new_accounts`, `discover.new_items`, `discover.run_skipped`, `discover.run_failed` to `GET /v1/events` (`new_rows` for the rows view, `new_accounts` for `view=accounts`, `new_items` for `view=items`; the two `run_` types say a slot did not run). To learn what needs your attention (a monitor whose webhook was paused, a failed Discover run, a call refused for credits), call `GET /v1/notifications?unread=true` once a minute or less: every item has a `title` and a `next_step`; then send the ids you handled to `POST /v1/notifications/read`. Both cost 0 credits.
- Paginate every list the same way: read `pagination.next_cursor` from the response, send it back verbatim as the `cursor` query parameter, and stop when `pagination.has_more` is `false`. Never build or decode a cursor yourself. Before you fetch the next page, read `pagination.next_page_credits` (what that page costs; `null` when there is none) and `pagination.typical_page_size` (rows a full page holds): a smaller page with `has_more: true` is a short page, not the end.
- Cached responses cost 0 credits (`cached: true`, `X-Cache: HIT`). Only send `Cache-Control: no-cache` when you truly need a live fetch; it is billed at the normal rate.
- Errors are machine-readable. On any `success: false`, branch on `error.type` and follow `error.doc_url` to the exact fix instead of guessing.
- On a `429` or `503`, honor the `Retry-After` response header: wait that many seconds, then retry the same request. Credits are refunded on `502`/`503`, so retrying is safe.
- If one platform keeps failing with `502`/`503`, call `GET /v1/status` before retrying again, or `GET /v1/status/{platform}` for that platform's endpoints and open incidents. Both are public (no API key) and cost 0 credits: a platform reported `degraded` or `down` will not recover by retrying sooner. To watch status from your own tooling, poll the Statuspage-compatible https://www.socialcrawl.dev/status/api/v2/summary.json or follow https://www.socialcrawl.dev/status/history.rss.
- Additive changes are never breaking: response fields are only ever added, never removed or renamed. Parse defensively and ignore unknown fields, and your integration keeps working across versions.
- Need the raw Markdown of any docs page for your context window? Append `.md` to the URL (e.g. `/docs/quickstart.md`, `/docs.md`, `/docs/api-reference.md`) instead of scraping the rendered HTML.

## Endpoint Categories
Example endpoints from the live registry (full catalog: https://www.socialcrawl.dev/llms.json):
- Profiles & channels (25 endpoints): /v1/tiktok/profile, /v1/instagram/profile, /v1/youtube/channel, /v1/twitter/profile
- Posts & videos (55 endpoints): /v1/tiktok/collection/videos, /v1/tiktok/effect/videos, /v1/tiktok/location/posts, /v1/tiktok/playlist/videos
- Comments (19 endpoints): /v1/tiktok/post/comments, /v1/instagram/post/comments, /v1/youtube/video/comments, /v1/reddit/post/comments
- Search (86 endpoints): /v1/tiktok/search, /v1/tiktok/search/hashtag, /v1/tiktok/search/mentions, /v1/tiktok/search/music
- Reviews & commerce (47 endpoints): /v1/aliexpress/product, /v1/aliexpress/reviews, /v1/amazon/product, /v1/amazon/product-search
- Transcripts & analysis (15 endpoints): /v1/tiktok/post/transcript, /v1/tiktok/trending, /v1/instagram/media/transcript, /v1/youtube/video/transcript

## Data & Statistics
Computed, dated social-media statistics: citable numbers refreshed on a cadence (https://www.socialcrawl.dev/data):
- What are the best hashtags for TikTok? Ranked live from the trending feed, with a date: https://www.socialcrawl.dev/data/best-hashtags-for-tiktok
- What are the best hashtags for Instagram? Ranked live from top Reels, with a date: https://www.socialcrawl.dev/data/best-hashtags-for-instagram
- What are the best hashtags for YouTube Shorts? Ranked live from the trending Shorts feed, with a date: https://www.socialcrawl.dev/data/best-hashtags-for-youtube-shorts
- What are the best hashtags for Instagram Reels? Ranked live from a real Reels sample, with a date: https://www.socialcrawl.dev/data/best-hashtags-for-instagram-reels
- What are the best hashtags for Instagram growth? Ranked live from growth-focused Reels, with a date: https://www.socialcrawl.dev/data/best-hashtags-for-instagram-growth
- Which TikTok hashtags drive the most views? Ranked live by average views per trending video, with a date: https://www.socialcrawl.dev/data/best-tiktok-hashtags-for-views
- What TikTok hashtags are trending this week? Ranked from videos posted in the last 7 days on the trending feed, with a date: https://www.socialcrawl.dev/data/trending-tiktok-hashtags-this-week
- What is the average TikTok engagement rate? Median (likes+comments+shares)/views across public videos, with a date: https://www.socialcrawl.dev/data/average-tiktok-engagement-rate
- What is the average Instagram engagement rate? Median interactions per view across public Reels, with a date: https://www.socialcrawl.dev/data/average-engagement-rate-instagram
- What is the average engagement rate on social media? Cross-platform median interactions per view across public TikTok + Instagram posts, with a date: https://www.socialcrawl.dev/data/average-engagement-rate
- Who is the most followed person on Instagram? Ranked live by follower count across the top public accounts, with a date: https://www.socialcrawl.dev/data/most-followed-person-on-instagram
- What is the most followed account on Instagram? Ranked live by follower count across the platform's largest public accounts INCLUDING brand, club and platform accounts, so Instagram's own @instagram account is counted rather than filtered out, which is why this answer differs from the most-followed PERSON page; the biggest account other than @instagram is reported separately, with a date: https://www.socialcrawl.dev/data/most-followed-on-instagram
- Who has the most followers on YouTube? Ranked live by subscriber count across the world's biggest channels, with a date: https://www.socialcrawl.dev/data/who-has-the-most-followers-on-youtube
- What is the most viewed video on YouTube? Ranked live by lifetime view count across the platform's most watched videos, with a date: https://www.socialcrawl.dev/data/most-viewed-youtube-video
- What is the most viewed TikTok? Ranked live by lifetime play count across videos from well-known creators, with a date: https://www.socialcrawl.dev/data/most-viewed-tiktok
- What is the most liked TikTok? Ranked live by lifetime like count across videos from well-known creators, with a date: https://www.socialcrawl.dev/data/most-liked-tiktok
- What is the most retweeted tweet? Ranked live by public retweet/repost count across historically most-retweeted posts, with a date: https://www.socialcrawl.dev/data/most-retweeted-tweet
- What is the most liked tweet? Ranked live by public like count across historically most-liked posts, with a date: https://www.socialcrawl.dev/data/most-liked-tweet
- What is the most streamed song on Spotify? Ranked live by playcount across a basket of the platform's most-streamed tracks, with a date: https://www.socialcrawl.dev/data/most-streamed-song-on-spotify
- Who is the most streamed artist on Spotify? Ranked live by MONTHLY LISTENERS (unique accounts that played the artist in the last 28 days) across a basket of the biggest global artists, because Spotify publishes no per-artist career stream total, with a date: https://www.socialcrawl.dev/data/most-streamed-artist-on-spotify
- What are the top podcasts on Spotify? Ranked live by HOW MANY LISTENERS RATED each show (with the 0-5 average alongside) across a basket of the biggest shows, because Spotify publishes no play, download, subscriber or follower count for a podcast, with a date: https://www.socialcrawl.dev/data/top-podcasts
- How much do YouTubers make? A net RPM band applied to the median views per video, computed live from real channel data, with a date: https://www.socialcrawl.dev/data/how-much-do-youtubers-make
- How much money do YouTubers make a month? Median views per video times real upload cadence times a cited net RPM band, computed live, with a date: https://www.socialcrawl.dev/data/how-much-money-do-youtubers-make
- How much do YouTubers make per view? The cited net RPM band expressed per view and per 1,000 views, anchored to the median views per video from real channel data, with a date: https://www.socialcrawl.dev/data/how-much-do-youtubers-make-per-view
- How many followers do you need to get paid on TikTok? TikTok's published Creator Rewards (10,000 followers + 100,000 views/30 days) and LIVE (1,000 followers) thresholds, plus the median follower count of real earning creators, dated: https://www.socialcrawl.dev/data/how-many-followers-on-tiktok-to-get-paid
- How many subscribers do you need to get paid on YouTube? YouTube's published Partner Program thresholds (1,000 subscribers + 4,000 watch hours in 12 months or 10,000,000 Shorts views in 90 days) and the expanded fan-funding tier (500 subscribers), plus the median subscriber count of real earning channels, dated: https://www.socialcrawl.dev/data/how-many-followers-on-youtube-to-get-paid
- How many followers do you need to get paid on Snapchat? Snapchat's published Monetization Program criteria (50,000 followers + 15,000 hours of view time in 28 days, of which 3,000 from Spotlight) which make a creator eligible for an INVITATION rather than paying automatically, plus the median follower count of real Snap Stars, dated: https://www.socialcrawl.dev/data/how-many-followers-on-snapchat-to-get-paid
- How many followers do you need to get paid on Twitch? Twitch's published Affiliate Path (25 followers + 4 stream hours + 4 unique days + 3 average concurrent viewers) which makes a streamer eligible for an INVITATION rather than paying automatically, plus the median follower count of real earning streamers, dated. Partner has no published follower floor.: https://www.socialcrawl.dev/data/how-many-followers-on-twitch-to-get-paid
- How many followers do you need to get paid on Instagram? Instagram's published Subscriptions (10,000 followers on a professional account) and Gifts on Reels (500 followers) thresholds, which are necessary but not automatic payment, plus the median follower count of real earning creators, dated. Live Badges have no published follower floor.: https://www.socialcrawl.dev/data/how-many-followers-on-instagram-to-get-paid
- How many followers do you need to get paid on Facebook? Facebook's published Subscriptions (10,000 followers or 250 return viewers) and Stars (500 followers for 30 consecutive days) thresholds, which are necessary but not automatic payment, plus the median follower count of real earning Pages, dated. Content Monetization is invite-only with no published follower floor; in-stream ads ended 31 August 2025.: https://www.socialcrawl.dev/data/how-many-followers-on-facebook-to-get-paid
- Which Naver blog keywords have the most posts? Korean lifestyle keywords ranked by the size of the published Naver blog corpus for each (content supply and ranking difficulty, not search volume), read live from Naver Search and dated: https://www.socialcrawl.dev/data/naver-blog-top-keywords
- Which Naver blog keywords are least competitive? Korean side hustle and personal finance keywords ranked by how many blog posts already compete for each, so the smallest corpus is the least crowded to enter (content supply, not search demand), read live from Naver Search and dated: https://www.socialcrawl.dev/data/naver-blog-keyword-competition
- Which topics are discussed most on Naver Cafe? Korean subjects ranked by how many articles members have written about each across Korea's largest community platform (cumulative discussion volume, not search volume and not a ranking of cafes), read live from Naver Search and dated: https://www.socialcrawl.dev/data/naver-cafe-most-discussed

## Authentication
x-api-key header (or Authorization: Bearer <key>) required on every request.
Get a free API key: https://www.socialcrawl.dev/auth/register

## Base URL
https://www.socialcrawl.dev/v1

## Quick Start
curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: sc_YOUR_API_KEY"

## Documentation
- API docs: https://www.socialcrawl.dev/docs
- AI agents guide: https://www.socialcrawl.dev/docs/ai-agents
- Machine-readable catalog: https://www.socialcrawl.dev/llms.json
- Concise overview: https://www.socialcrawl.dev/llms.txt
- Full endpoint reference: https://www.socialcrawl.dev/llms-full.txt
- OpenAPI spec: https://www.socialcrawl.dev/v1/openapi.json
- Per-platform OpenAPI: https://www.socialcrawl.dev/openapi/index.json (one document per platform at /openapi/{platform}.json)

## Contact
- Email: socialcrawl@ridio.io

## Allowed for AI Crawlers
All content at /, /docs, /blog, /changelog, /platforms, /pricing, /solutions, /vs, /tools, /data
is free to index and cite. /v1/openapi.json, /openapi/{platform}.json and the /llms*.txt files are fetchable without auth.
Do not crawl /api, /v1 data endpoints, /dashboard, /auth, /admin.