# Introduction (/docs) One API key and one JSON shape for public data from every platform SocialCrawl covers. Your first call is on this page and takes under a second. SocialCrawl returns public data from 65 platforms through 572 endpoints. Every request uses one `x-api-key` header, and every response comes back in the same JSON shape, so one parser covers every platform. You do not need an account to try it. Press **Run** below. If you are signed in, your own API key is already filled into every sample on this page. ## Make your first call ```bash curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \ -H "x-api-key: YOUR_API_KEY" ``` Three things just happened. You sent one GET request with one header. The platform answered in well under a second on a normal connection. The call cost 1 credit, and your balance came back in the same response, so you always know where you stand. } title="Get your API key" href="/auth/register?redirectTo=%2Fdocs%2Fquickstart" description="Create a free account for 100 credits and your own key, filled into every sample here." /> } title="Try it in the Explorer" href="/explorer" description="Run any of the endpoints in the browser without writing code." /> ## Same call, different platform Change one path segment and the same request reads a different platform. Same header, same `handle` parameter, same response shape. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=nasa" \ -H "x-api-key: YOUR_API_KEY" curl "https://www.socialcrawl.dev/v1/instagram/profile?handle=nasa" \ -H "x-api-key: YOUR_API_KEY" curl "https://www.socialcrawl.dev/v1/youtube/channel?handle=nasa" \ -H "x-api-key: YOUR_API_KEY" curl "https://www.socialcrawl.dev/v1/twitter/profile?handle=nasa" \ -H "x-api-key: YOUR_API_KEY" ``` You do not learn four APIs. Field coverage differs where the platforms differ, and each endpoint's exact response shape is one free call away (see below). ## Read the response Every response, success or failure, has the same top level. The platform data is always under `data`. ```json title="Response" { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile", "data": { "author": { "username": "nasa", "followers": 3900000 } }, "credits_used": 1, "credits_remaining": 99, "request_id": "req-abc123", "cached": false } ``` | Field | What to do with it | | ------------------- | ------------------------------------------------------------------------------- | | `success` | Branch on this first. When it is `false`, `error.type` says what went wrong. | | `data` | The platform payload. Profile calls return `author`, list calls return `items`. | | `credits_used` | The net charge for this call. Cache hits and failures are 0. | | `credits_remaining` | Your balance after this call. No separate balance call needed. | | `request_id` | Quote it to support and we can see exactly what happened. | List endpoints add a `pagination` block. Send `next_cursor` back as `cursor` and stop when `has_more` is `false`. That rule is the same on every list endpoint. See [Pagination](/docs/pagination.md) and [Response schema](/docs/response-schema.md). When an endpoint supports a computed field and the required source inputs are present, the response also carries it under `computed`, for example `engagement_rate`. A field that cannot be computed is `null`, never a guess. See [Computed fields](/docs/computed-fields.md). ## Explore the catalogue for free Every `/v1/utility/*` endpoint and `/v1/credits/balance` cost 0 credits. They answer in about 150 ms and are generated from the endpoint registry at request time, so they cannot drift from what is callable. Use them instead of reading 572 reference pages. ```bash title="cURL" # Everything you need for a first call, in one JSON document curl "https://www.socialcrawl.dev/v1/utility/quickstart?platform=instagram" \ -H "x-api-key: YOUR_API_KEY" # Search every endpoint by keyword. Try "comments", "reviews", "transcript" curl "https://www.socialcrawl.dev/v1/utility/endpoints?search=comments" \ -H "x-api-key: YOUR_API_KEY" # The full guide for one endpoint: parameters, cost, paging, an example call curl "https://www.socialcrawl.dev/v1/utility/endpoint?id=youtube/channel" \ -H "x-api-key: YOUR_API_KEY" # Your balance curl "https://www.socialcrawl.dev/v1/credits/balance" \ -H "x-api-key: YOUR_API_KEY" ``` ## Hand it to your AI agent If Claude, Cursor, ChatGPT, or another agent writes your code, give it the same catalogue. The MCP server and the Agent Skill both call it before every request, so the agent never guesses a path or a parameter. The [Using an AI agent](/docs/quickstart/agents.md) page has a prompt you can paste as it is. ```bash title="cURL" # Claude Code (hosted MCP, nothing to install) claude mcp add --transport http socialcrawl https://mcp.socialcrawl.dev/mcp \ --header "Authorization: Bearer YOUR_API_KEY" # Any MCP client, local package npx -y socialcrawl-mcp ``` Every docs page is also plain Markdown: append `.md` to its URL. The machine index is at [/llms.txt](/llms.txt), the per-platform context is at `/v1/utility/llms?platform=tiktok`, and the full spec is at [/v1/openapi.json](/v1/openapi.json). See [AI agents](/docs/ai-agents.md) and [Skills and MCP](/docs/skills-and-mcp.md). ## What a call costs New accounts start with 100 credits and no card. Most endpoints cost 1 credit. Cache hits cost 0. Failed calls and empty results are refunded automatically. Invalid parameters are rejected before billing. A small set of endpoints has a flat or metered price instead of a tier. The exact figure for every endpoint is in [Endpoint pricing](/docs/endpoint-pricing.md) and in the `credits` field of `/v1/utility/endpoints`. Rate limits are 600 requests per minute and 50 in flight per key. See [Credits](/docs/credits.md) and [Rate limits](/docs/rate-limits.md). ## When something goes wrong Errors use the same JSON shape with `success: false`. Branch on `error.type`, never on the message text. Every error carries a `doc_url` that links to the fix. | `error.type` | HTTP | Meaning and fix | | ---------------------- | ---- | -------------------------------------------------------------------------------------- | | `MISSING_API_KEY` | 401 | No `x-api-key` header reached us. Add it, and check that a proxy is not stripping it. | | `INVALID_API_KEY` | 401 | The key is malformed, revoked, or unknown. Copy it again from the dashboard. | | `INVALID_REQUEST` | 400 | A required parameter is missing or invalid. Never billed. The message names the field. | | `INSUFFICIENT_CREDITS` | 402 | Your balance is below the endpoint's cost. Top up, or wait for a cache hit. | | `ENDPOINT_NOT_FOUND` | 404 | SocialCrawl does not have that platform or resource. Search the catalogue. | | `RESOURCE_NOT_FOUND` | 404 | The platform does not have that item. This is a real answer, and it is refunded. | | `CONCURRENCY_LIMIT` | 429 | More than 50 requests in flight on one key. Honor `Retry-After`, then continue. | `ENDPOINT_NOT_FOUND` means we do not have it. `RESOURCE_NOT_FOUND` means the platform does not have it. The full table, with which codes are safe to retry, is in [Errors](/docs/errors.md). ## Next You made a call. The [Quickstart](/docs/quickstart.md) walks you through your first 100 calls: your own key, several platforms in one script, one search across every platform, and the free catalogue from your terminal. - [Quickstart](/docs/quickstart.md): Your key, your first 100 calls across several platforms, and the free catalogue. - [Pagination](/docs/pagination.md): One rule for every list: send next_cursor back as cursor. - [API Reference](/docs/api-reference.md): Every endpoint with an interactive playground and full response schemas. - [Recipes](/docs/recipes.md): Runnable TypeScript builds, each with its credit cost attached. ## Which platforms does SocialCrawl support? ## Frequently asked questions ## All documentation pages Append `.md` to any `/docs/...` URL to read that page as Markdown. - [AI Agent Integration](/docs/ai-agents.md) - [Authentication](/docs/authentication.md) - [Batch endpoints](/docs/batch.md) - [Billing Webhooks](/docs/billing-webhooks.md) - [Caching](/docs/caching.md) - [Which Endpoint Should I Use?](/docs/choosing-endpoints.md) - [Claude Code](/docs/claude-code.md) - [Cohorts](/docs/cohorts.md) - [Computed fields](/docs/computed-fields.md) - [Credits](/docs/credits.md) - [Data Availability](/docs/data-availability.md) - [Endpoint pricing](/docs/endpoint-pricing.md) - [Enterprise](/docs/enterprise.md) - [Error Handling](/docs/errors.md) - [Introduction](/docs.md) - [LangChain](/docs/langchain.md) - [Metric substitutions](/docs/metric-substitutions.md) - [n8n](/docs/n8n.md) - [Pagination](/docs/pagination.md) - [Production Checklist](/docs/production-checklist.md) - [Rate Limits](/docs/rate-limits.md) - [Response Schema](/docs/response-schema.md) - [Schema compatibility](/docs/schema-compatibility.md) - [Security](/docs/security.md) - [Skills & MCP Server](/docs/skills-and-mcp.md) - [Streaming (SSE)](/docs/streaming.md) - [Testing Your Integration](/docs/testing-your-integration.md) - [Vercel AI SDK](/docs/vercel-ai-sdk.md) - [Versioning & Deprecation](/docs/versioning.md) - [Monitor Webhooks](/docs/webhooks.md) - [AliExpress](/docs/aliexpress.md) - [Amazon](/docs/amazon.md) - [Apple App Store](/docs/app_store.md) - [Apple Music](/docs/apple_music.md) - [Bluesky](/docs/bluesky.md) - [Content Analysis](/docs/content_analysis.md) - [Douyin](/docs/douyin.md) - [eBay](/docs/ebay.md) - [Etsy](/docs/etsy.md) - [Facebook](/docs/facebook.md) - [Google Finance](/docs/finance.md) - [G2](/docs/g2.md) - [GitHub](/docs/github.md) - [Google](/docs/google.md) - [Google News](/docs/google_news.md) - [Google Play](/docs/google_play.md) - [Google Shopping](/docs/google_shopping.md) - [Google Trends](/docs/google_trends.md) - [Gumtree](/docs/gumtree.md) - [Hacker News](/docs/hackernews.md) - [H&M](/docs/hm.md) - [Home Depot](/docs/home_depot.md) - [Instagram](/docs/instagram.md) - [Jobs](/docs/jobs.md) - [Kick](/docs/kick.md) - [Klarna](/docs/klarna.md) - [Kohl's](/docs/kohls.md) - [Komi](/docs/komi.md) - [Kwai](/docs/kwai.md) - [LinkBio](/docs/linkbio.md) - [LinkedIn](/docs/linkedin.md) - [LinkMe](/docs/linkme.md) - [Linktree](/docs/linktree.md) - [Naver](/docs/naver.md) - [On-Page](/docs/on_page.md) - [Perplexity](/docs/perplexity.md) - [Pillar](/docs/pillar.md) - [Pinterest](/docs/pinterest.md) - [Polymarket](/docs/polymarket.md) - [Prism](/docs/prism.md) - [Using an AI agent](/docs/quickstart/agents.md) - [Quickstart](/docs/quickstart.md) - [Quora](/docs/quora.md) - [Ad library aggregation](/docs/recipes/ads-library-aggregation.md) - [Brand mention monitoring](/docs/recipes/brand-mention-monitoring.md) - [Competitor tracking](/docs/recipes/competitor-tracking.md) - [Creator engagement scoring](/docs/recipes/creator-engagement-scoring.md) - [Recipes](/docs/recipes.md) - [Music trend detection](/docs/recipes/music-trend-detection.md) - [Hybrid search-then-enrich](/docs/recipes/search-then-enrich.md) - [Sentiment analysis](/docs/recipes/sentiment-analysis.md) - [Social listening pulse-check](/docs/recipes/social-listening-pulse-check.md) - [TikTok analytics dashboard](/docs/recipes/tiktok-analytics-dashboard.md) - [Video transcription](/docs/recipes/video-transcription-api.md) - [Reddit](/docs/reddit.md) - [Rumble](/docs/rumble.md) - [App schema](/docs/schema/app.md) - [Author schema](/docs/schema/author.md) - [Comment schema](/docs/schema/comment.md) - [Cross-platform field equivalence](/docs/schema/field-equivalence.md) - [Unified schema](/docs/schema.md) - [Job schema](/docs/schema/job.md) - [Media list schema](/docs/schema/media-list.md) - [News article schema](/docs/schema/news-article.md) - [Place schema](/docs/schema/place.md) - [Post schema](/docs/schema/post.md) - [Product schema](/docs/schema/product.md) - [Quote schema](/docs/schema/quote.md) - [Review schema](/docs/schema/review.md) - [Seller schema](/docs/schema/seller.md) - [Transcript schema](/docs/schema/transcript.md) - [Web page schema](/docs/schema/web-page.md) - [Universal social search](/docs/search/everywhere.md) - [Universal Search](/docs/search.md) - [Universal news search](/docs/search/news.md) - [Sephora](/docs/sephora.md) - [Snapchat](/docs/snapchat.md) - [Spotify](/docs/spotify.md) - [Target](/docs/target.md) - [Tavily](/docs/tavily.md) - [Telegram](/docs/telegram.md) - [Threads](/docs/threads.md) - [TikTok](/docs/tiktok.md) - [TikTok Shop](/docs/tiktokshop.md) - [Tripadvisor](/docs/tripadvisor.md) - [Trustpilot](/docs/trustpilot.md) - [Truth Social](/docs/truthsocial.md) - [Twitch](/docs/twitch.md) - [US Congress Trades](/docs/us_congress_trades.md) - [Utility](/docs/utility.md) - [Walmart](/docs/walmart.md) - [Wayfair](/docs/wayfair.md) - [Yelp](/docs/yelp.md) - [YouTube](/docs/youtube.md) - [Twitter/X](/docs/twitter.md) - [Web Scraping](/docs/web.md) - [API Reference](/docs/api-reference.md)