ScrapeWhale API

{"openapi":"3.1.0","info":{"title":"ScrapeWhale API","version":"1.0.0","summary":"Web data for marketing agents: traffic, ads, social profiles, and clean markdown from any URL or file — every endpoint returns structured JSON and/or agent-ready markdown.","description":"Web data for marketing agents: traffic, ads, social profiles, and clean markdown from any URL or file — every endpoint returns structured JSON and/or agent-ready markdown.\n\nEvery response is built for agents: structured `data` for post-processing,\nclean `markdown` for dropping straight into a context window — your choice\nper request. Machine-readable spec: [/openapi.json](/openapi.json) · agent\nsummary: [/llms.txt](/llms.txt).\n\n# Getting started\n\n## Quick start\n\nCreate an API key at [/settings/apikeys](/settings/apikeys) — new accounts get\n**10 free credits**, no card required. Then make your first call:\n\n```bash\ncurl 'https://scrapewhale.dev/api/v1/traffic?domain=nike.com' \\n  -H 'Authorization: Bearer <api-key>'\n```\n\nOr pull a full brand dossier — logo, traffic, authority, ads, and the homepage\nas markdown, in one call:\n\n```bash\ncurl 'https://scrapewhale.dev/api/v1/brand?domain=nike.com' \\n  -H 'Authorization: Bearer <api-key>'\n```\n\n## Authentication\n\nCreate an API key at **/settings/apikeys**, then send it on every request:\n\n```\nAuthorization: Bearer <api-key>\n```\n\n(`x-api-key: <api-key>` also works.) Keys are rate-limited to 60 requests\nper minute; credits are the real spend cap. Logged-in users can also run every\nendpoint from the **Playground** at [/playground](/playground) — same\nendpoints, same credits.\n\n## Credits\n\nEvery successful request consumes credits from your balance (new accounts\nstart with 10 free credits; credit packs never expire):\n\n| Endpoints | Credits |\n| --- | --- |\n| URL / file → markdown, search, maps, trends, social profiles, X/Twitter posts, YouTube video/channel/transcript/search, TikTok Shop lookups, Shopify catalogue, Google ad creative/advertiser, traffic & SEO metrics, domain facts, Chrome Web Store | 1 |\n| Ads endpoints, the TikTok Shop catalog, and AI Overview (heavy upstream crawls/renders) | 2 |\n\n**Failed requests are refunded automatically** — you are never charged for an\nerror. **Cache hits are free**: data endpoints serve recently-fetched public\ndata (6–24h freshness windows; logos 7 days) from a shared cache at no credit\ncost — the response carries `\"cached\": true` and `\"creditsCharged\": 0`.\n\n## Output formats\n\nExtraction endpoints accept `?format=json|markdown|both` (default `both`):\n\n- `json` — structured payload only (`data`)\n- `markdown` — clean markdown only (`markdown`)\n- `both` — both fields in one response\n\nBoth artifacts are stored with the conversion and can be re-fetched later via\n`GET /api/v1/conversions/{id}`.\n\n# Errors\n\nErrors are JSON `{ \"error\": \"<message>\", \"code\": \"<code>\" }`:\n\n| Status | Meaning |\n| --- | --- |\n| 400 | Invalid parameters |\n| 401 | Missing or invalid API key |\n| 402 | Insufficient credits |\n| 404 | Not found |\n| 422 | Extraction/conversion failed (`code` carries the failure category; credits refunded) |\n| 429 | Rate limit exceeded |\n\nFile uploads can additionally return 413 (over 10 MB) or 415 (unsupported or\nblocked type — HTML files are rejected; convert web pages by URL instead).\n\n# Integrations\n\n## MCP server\n\nA hosted MCP server at `https://scrapewhale.dev/mcp` (Streamable HTTP)\nexposes every endpoint as tools, grouped by platform (`youtube`, `ads`,\n`domain_intel`, `google_trends`, …), plus `brand_dossier` and\n`get_result`. Nothing to install: sign in with your ScrapeWhale account,\nor send the same API key as REST. Tool calls cost the same credits as the\nmatching endpoint.\n\n**Claude (claude.ai / Desktop)** — Settings → Connectors → *Add custom\nconnector*, URL `https://scrapewhale.dev/mcp` and sign in..."},"servers":[{"url":"https://scrapewhale.dev"}],"tags":[{"name":"Web"},{"name":"Search"},{"name":"Maps"},{"name":"Trends"},{"name":"Traffic & SEO"},{"name":"Domain"},{"name":"Chrome Web Store"},{"name":"Ads"},{"name":"Brand"},{"name":"Social"},{"name":"TikTok Shop"},{"name":"Shopify"},{"name":"Conversions"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{}}