llms.txt
Compare with other sites' llms.txt files →# SocialCrawl API
> Unified social media data API. One API key, one response format, 75 platforms, 733 endpoints.
Last updated: 2026-11-08
## Base URL
https://www.socialcrawl.dev/v1
## Authentication
Pass your API key in the `x-api-key` header with every request, or as `Authorization: Bearer <key>` if your client prefers that.
## 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 23 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 one fused, ranked search across the platforms it covers at a flat 20 credits a search, call `/v1/search/everywhere`; for a collection of more than 100 rows or more than one page per platform, call `/v1/prism/discover`; for creators, `/v1/prism/creators`; to be told what is new, send `since_watermark` with the `data.next.watermark` of your last answer, or turn the search into a watch with its `data.next.watch`. Start with `GET /v1/search/everywhere?query=Liquid%20Death&period=7d&format=compact&limit=20&deadline_s=25`; the guide is /docs/search/everywhere.
- 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 a creator's email ("find this creator's email"): To get the business email a creator publishes, for a creator you already have, call that creator's profile with `include=contacts` (`/v1/youtube/channel/about`, `/v1/instagram/profile`, `/v1/tiktok/profile`, `/v1/twitter/profile` or `/v1/facebook/profile`) and read `author.ext.contacts`; a `data.contact_lookup.status` of `partial`, `gated_pending` or `unavailable` means not yet, never no email. To find creators you do not have yet, call `/v1/prism/creators` first.
- 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/search/everywhere` with `schedule` (every `1h` or slower, `dry_run` first), at 20 credits a search per fire and only rows that watch has not delivered, read through `GET /v1/events`, a webhook endpoint or the watch's own `last_fire`; 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 300 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 or empty 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.
## Start here
- Several platforms, a date window, every row judged and de-duplicated: `GET https://www.socialcrawl.dev/v1/prism/discover?brands={brand}&period=last_month&max_credits=150` ([guide](https://www.socialcrawl.dev/docs/prism/discover), [agent tools](https://www.socialcrawl.dev/docs/prism/discover-agents), [OpenAPI](https://www.socialcrawl.dev/openapi/prism-discover.json))
- Creators or influencers by topic, market, size or a product to promote: `GET https://www.socialcrawl.dev/v1/prism/creators?keywords={topic}&country={country}&dry_run=true` ([guide](https://www.socialcrawl.dev/docs/prism/creators), [OpenAPI](https://www.socialcrawl.dev/openapi/prism-creators.json)); agent tools: `socialcrawl_find_creators` starts a creator search (dry run first), shows `data.request.compiled` and the estimate, and relays `next_step`; `socialcrawl_creators_run` reads and steers a run: `list`, `wait`, `results`, `changes`, `resume`, `cancel` and `more`; reading is free; `socialcrawl_creators_manage` saves a run's creators and follows their new posts, showing the follow's dry run first; its writes carry an `Idempotency-Key`
- One platform: that platform's own search, listed in its `llms-{platform}.txt` below.
- Listening: watch keywords or boolean topics on Reddit, YouTube, X, Naver, Google News, TikTok, Facebook, Threads and LinkedIn on a schedule you choose, and receive only new, relevant mentions through a cursor feed, a named consumer or a signed webhook. Start with `POST https://www.socialcrawl.dev/v1/listening/streams?dry_run=1` (0 credits, creates nothing); add `"comments": "new_posts"` to also read the comments under the Reddit posts it keeps; agents read [/docs/listening/agents](https://www.socialcrawl.dev/docs/listening/agents) first ([guide](https://www.socialcrawl.dev/docs/listening/quickstart), [OpenAPI](https://www.socialcrawl.dev/openapi/listening.json))
## Platforms
- [airbnb](https://www.socialcrawl.dev/llms-airbnb.txt): 4 endpoints
- [aliexpress](https://www.socialcrawl.dev/llms-aliexpress.txt): 9 endpoints
- [amazon](https://www.socialcrawl.dev/llms-amazon.txt): 8 endpoints
- [app_store](https://www.socialcrawl.dev/llms-app_store.txt): 9 endpoints
- [apple_music](https://www.socialcrawl.dev/llms-apple_music.txt): 5 endpoints
- [bing](https://www.socialcrawl.dev/llms-bing.txt): 4 endpoints
- [bluesky](https://www.socialcrawl.dev/llms-bluesky.txt): 4 endpoints
- [booking](https://www.socialcrawl.dev/llms-booking.txt): 3 endpoints
- [content_analysis](https://www.socialcrawl.dev/llms-content_analysis.txt): 10 endpoints
- [douyin](https://www.socialcrawl.dev/llms-douyin.txt): 8 endpoints
- [duckduckgo](https://www.socialcrawl.dev/llms-duckduckgo.txt): 7 endpoints
- [ebay](https://www.socialcrawl.dev/llms-ebay.txt): 2 endpoints
- [economy](https://www.socialcrawl.dev/llms-economy.txt): 5 endpoints
- [etsy](https://www.socialcrawl.dev/llms-etsy.txt): 4 endpoints
- [facebook](https://www.socialcrawl.dev/llms-facebook.txt): 32 endpoints
- [finance](https://www.socialcrawl.dev/llms-finance.txt): 8 endpoints
- [g2](https://www.socialcrawl.dev/llms-g2.txt): 7 endpoints
- [gab](https://www.socialcrawl.dev/llms-gab.txt): 5 endpoints
- [github](https://www.socialcrawl.dev/llms-github.txt): 12 endpoints
- [goodreads](https://www.socialcrawl.dev/llms-goodreads.txt): 10 endpoints
- [google](https://www.socialcrawl.dev/llms-google.txt): 13 endpoints
- [google_news](https://www.socialcrawl.dev/llms-google_news.txt): 1 endpoint
- [google_play](https://www.socialcrawl.dev/llms-google_play.txt): 9 endpoints
- [google_shopping](https://www.socialcrawl.dev/llms-google_shopping.txt): 5 endpoints
- [google_trends](https://www.socialcrawl.dev/llms-google_trends.txt): 3 endpoints
- [gumtree](https://www.socialcrawl.dev/llms-gumtree.txt): 11 endpoints
- [hackernews](https://www.socialcrawl.dev/llms-hackernews.txt): 4 endpoints
- [hm](https://www.socialcrawl.dev/llms-hm.txt): 6 endpoints
- [home_depot](https://www.socialcrawl.dev/llms-home_depot.txt): 4 endpoints
- [instagram](https://www.socialcrawl.dev/llms-instagram.txt): 44 endpoints
- [jobs](https://www.socialcrawl.dev/llms-jobs.txt): 11 endpoints
- [kick](https://www.socialcrawl.dev/llms-kick.txt): 1 endpoint
- [klarna](https://www.socialcrawl.dev/llms-klarna.txt): 18 endpoints
- [kohls](https://www.socialcrawl.dev/llms-kohls.txt): 5 endpoints
- [komi](https://www.socialcrawl.dev/llms-komi.txt): 1 endpoint
- [kwai](https://www.socialcrawl.dev/llms-kwai.txt): 3 endpoints
- [linkbio](https://www.socialcrawl.dev/llms-linkbio.txt): 1 endpoint
- [linkedin](https://www.socialcrawl.dev/llms-linkedin.txt): 77 endpoints
- [linkme](https://www.socialcrawl.dev/llms-linkme.txt): 1 endpoint
- [linktree](https://www.socialcrawl.dev/llms-linktree.txt): 1 endpoint
- [naver](https://www.socialcrawl.dev/llms-naver.txt): 20 endpoints
- [on_page](https://www.socialcrawl.dev/llms-on_page.txt): 1 endpoint
- [perplexity](https://www.socialcrawl.dev/llms-perplexity.txt): 1 endpoint
- [pillar](https://www.socialcrawl.dev/llms-pillar.txt): 1 endpoint
- [pinterest](https://www.socialcrawl.dev/llms-pinterest.txt): 6 endpoints
- [polymarket](https://www.socialcrawl.dev/llms-polymarket.txt): 2 endpoints
- [prism](https://www.socialcrawl.dev/llms-prism.txt): 53 endpoints
- [producthunt](https://www.socialcrawl.dev/llms-producthunt.txt): 5 endpoints
- [quora](https://www.socialcrawl.dev/llms-quora.txt): 7 endpoints
- [reddit](https://www.socialcrawl.dev/llms-reddit.txt): 14 endpoints
- [rumble](https://www.socialcrawl.dev/llms-rumble.txt): 5 endpoints
- [search](https://www.socialcrawl.dev/llms-search.txt): 6 endpoints
- [sephora](https://www.socialcrawl.dev/llms-sephora.txt): 11 endpoints
- [snapchat](https://www.socialcrawl.dev/llms-snapchat.txt): 2 endpoints
- [spotify](https://www.socialcrawl.dev/llms-spotify.txt): 6 endpoints
- [target](https://www.socialcrawl.dev/llms-target.txt): 5 endpoints
- [tavily](https://www.socialcrawl.dev/llms-tavily.txt): 4 endpoints
- [telegram](https://www.socialcrawl.dev/llms-telegram.txt): 4 endpoints
- [threads](https://www.socialcrawl.dev/llms-threads.txt): 6 endpoints
- [tiktok](https://www.socialcrawl.dev/llms-tiktok.txt): 38 endpoints
- [tiktokshop](https://www.socialcrawl.dev/llms-tiktokshop.txt): 6 endpoints
- [tripadvisor](https://www.socialcrawl.dev/llms-tripadvisor.txt): 16 endpoints
- [trustpilot](https://www.socialcrawl.dev/llms-trustpilot.txt): 3 endpoints
- [truthsocial](https://www.socialcrawl.dev/llms-truthsocial.txt): 3 endpoints
- [twitch](https://www.socialcrawl.dev/llms-twitch.txt): 4 endpoints
- [twitter](https://www.socialcrawl.dev/llms-twitter.txt): 18 endpoints
- [us_congress_trades](https://www.socialcrawl.dev/llms-us_congress_trades.txt): 19 endpoints
- [utility](https://www.socialcrawl.dev/llms-utility.txt): 13 endpoints
- [walmart](https://www.socialcrawl.dev/llms-walmart.txt): 5 endpoints
- [wayfair](https://www.socialcrawl.dev/llms-wayfair.txt): 3 endpoints
- [web](https://www.socialcrawl.dev/llms-web.txt): 22 endpoints
- [weibo](https://www.socialcrawl.dev/llms-weibo.txt): 8 endpoints
- [xiaohongshu](https://www.socialcrawl.dev/llms-xiaohongshu.txt): 6 endpoints
- [yelp](https://www.socialcrawl.dev/llms-yelp.txt): 5 endpoints
- [youtube](https://www.socialcrawl.dev/llms-youtube.txt): 30 endpoints
## Credits
- Standard: 1 credit per request (418 endpoints)
- Advanced: 5 credits per request (269 endpoints)
- Premium: 10 credits per request (46 endpoints)
## Caching
- Successful responses are cached and shared across your account; cache hits cost 0 credits (`cached: true`, `X-Cache: HIT`).
- Freshness windows by data type: profiles ~15m, posts ~10m, comments ~5m, search ~2m, analytics ~30m.
- Force a live fetch with the `Cache-Control: no-cache` request header (billed at the normal rate; writes the fresh result back for the next caller). `no-store` alone does not trigger it.
## Idempotency
- Send an `Idempotency-Key` (UUID) request header to make a call safely retriable. Keys are reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. Completed outcomes expire after 24 hours. The claim store fails closed before billing. A replay keeps the cached payload immutable except for billing metadata: `credits_used` is 0 and `idempotent_replay` is true. A known current balance is refreshed in body `credits_remaining` and the `X-Credits-Remaining` header; no balance row resolves to 0. On a transient balance lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. If a completed body exceeded the 64 KB replay limit, the same key receives `409 IDEMPOTENCY_REPLAY_UNAVAILABLE`; use a new key only to make a new billable request. GET Server-Sent Event requests cannot be replayed: use `Accept: application/json` when sending an idempotency key. The unsupported key-plus-SSE combination returns an unbilled `400 INVALID_REQUEST`. POST batch SSE keeps its documented sync-equivalent replay behavior.
## Common Agent Tasks
### Jobs
Customers arrive with a job, not an endpoint name. Each job below is the call (or chain) that does it, the example to copy, and the price of one run in credits. For a job in your own words, GET /v1/utility/plan?query=<the job> returns the calls with your values filled in. The same jobs, with a cURL each: /docs/common-jobs.
- Watch a brand: GET /v1/prism/brand-mentions?keyword=socialcrawl&date_from={start_date}&include=digest (50 credits). Find recent mentions of a brand on news sites, blogs and forums across the web, with a summary of what they say.
- What people say under a post: GET /v1/tiktok/post/comments?url=https%3A%2F%2Fwww.tiktok.com%2F%40stoolpresidente%2Fvideo%2F7623818255903329566&label=question%2Ccomplaint%2Cpurchase_intent (1 credit). Read the comments on a post and see which are questions, complaints or buyers, without judging them yourself.
- Mine comments for buyers: GET /v1/prism/comments?url=https%3A%2F%2Fwww.tiktok.com%2F%40stoolpresidente%2Fvideo%2F7623818255903329566 (2 to 120 credits). Collect up to 1,000 comments on a post, with replies on the top 100, and keep the ones that show buying intent.
- Profile, posts and comments for one creator: GET /v1/tiktok/profile?handle=charlidamelio → GET /v1/tiktok/profile/videos?handle=charlidamelio → GET /v1/tiktok/post/comments?url={url} (3 credits). Get a creator's profile, their recent posts, and the comments on one of those posts.
- One creator on every platform: GET /v1/prism/creator-card?handle=mrbeast&platforms=tiktok%2Cinstagram%2Cyoutube%2Ctwitter (5 credits). See the same creator's profiles on TikTok, Instagram, YouTube and X in one call.
- Track a creator daily: GET /v1/instagram/profile/posts?handle=instagram&since={last_run_date} (1 credit). Poll a creator's new posts every day, stopping at the date of your last run so each poll pays only for the pages it reads.
- Find creators in a niche: GET /v1/prism/creators?keywords=skincare+routine&platforms=tiktok%2Cinstagram&min_followers=50000 (0 to 200 credits). Find creators or influencers who post about a topic, filtered by platform, market and size, each measured from its recent posts and ranked with its reasons.
- Vet a creator: GET /v1/prism/creator-vet?handle=mkbhd&platform=youtube (50 credits). Check a creator before a partnership: audience, engagement and brand-safety signals in one call.
- Find a creator's email: GET /v1/youtube/channel/about?handle=Google&include=contacts (25 credits). Get the business email a creator publishes, for a creator you alread