# Build with AI Source: https://docs.stophy.dev/ai-onboarding Set up an AI agent with Stophy. Get a key, connect the MCP server, and give it agents.md, llms.txt and the live endpoint catalog. Give your agent [stophy.dev/agents.md](https://stophy.dev/agents.md) and it can pick an endpoint and add Stophy to your project. ## Connect over MCP > [card] [MCP server](/mcp-server) > > Set up Codex, Claude Code, Cursor, OpenCode or another client. ## Your agent harness > [card] [Codex](/quickstarts/codex) > [card] [Claude Code](/quickstarts/claude-code) > [card] [Cursor](/quickstarts/cursor) > [card] [Claude Desktop](/quickstarts/claude-desktop) OpenCode setup is in [MCP without a key or with one](/mcp-server/keyless). ## Your LLM SDK > [card] [OpenAI](/developer-guides/llm-sdks/openai) > > Call Stophy from an OpenAI tool. > [card] [Anthropic](/developer-guides/llm-sdks/anthropic) > > Call Stophy from a Claude tool. > [card] [Vercel AI SDK](/developer-guides/llm-sdks/vercel-ai-sdk) > > Use Stophy with the AI SDK. > [card] [Resources for agents](/resources) > > agents.md, llms.txt, the OpenAPI document and the endpoint catalog. # Batch scrape Source: https://docs.stophy.dev/api-reference/endpoint/batch-scrape api-reference/openapi.json POST /v1/batch/scrape Scrape many pages in the background. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. Best for a list of addresses you already have. It answers at once with an id; ask batch.scrape.status for the pages, or send webhook to be told as each one finishes. ## Price 1 credit a page, however it is reached. json with a schema or a prompt, summary and highlights add 4 credits each when they return something. CSS rules and attributes add nothing. A PDF adds 1 credit for each page read. Each perform action adds 2 credits. An answer from a stored copy within maxAge is free. A page that comes back with a 404 or 410 status is charged like any page. A page that cannot be read costs nothing. Each page is charged when it finishes. Starting the job is free. See [Pricing](/billing) for what credits cost. ## Limits An account runs up to 5 crawls and batch scrapes at once. A sixth start answers 400 `invalidRequest`: `jobs: you already have 5 jobs running. Wait for one of them to finish, then try again.` Wait until one is `completed`, then start it again. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/batch/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"urls":["https://bun.com/docs/runtime/bunfig","https://bun.com/docs/runtime/env"]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/batch/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ urls: [ "https://bun.com/docs/runtime/bunfig", "https://bun.com/docs/runtime/env", ], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/batch/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "urls": [ "https://bun.com/docs/runtime/bunfig", "https://bun.com/docs/runtime/env", ], }, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "id": "job_385XD5MMpQfsXsGFdTO9vQ", "url": "https://api.stophy.dev/v1/batch/scrape/job_385XD5MMpQfsXsGFdTO9vQ", "invalidURLs": [] } ``` # Cancel a batch scrape Source: https://docs.stophy.dev/api-reference/endpoint/batch-scrape-cancel api-reference/openapi.json DELETE /v1/batch/scrape/{id} Stop a batch scrape and keep the pages already read. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. ```bash cURL theme={null} curl -X DELETE https://api.stophy.dev/v1/batch/scrape/job_KO-8zdOlvRgOuItwdf-60w \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/batch/scrape/job_KO-8zdOlvRgOuItwdf-60w", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.delete( "https://api.stophy.dev/v1/batch/scrape/job_KO-8zdOlvRgOuItwdf-60w", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "status": "cancelled" } ``` # Batch scrape errors Source: https://docs.stophy.dev/api-reference/endpoint/batch-scrape-errors api-reference/openapi.json GET /v1/batch/scrape/{id}/errors List the pages a batch scrape could not read, and why. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. ## Failed pages Lists every page the job could not read, up to 1,000, each with `url`, `code`, `message`, `retryable` and `at`. `isTruncated` is `true` when there are more. Retry a page when `retryable` is `true`. > [!WARNING] > > No example is recorded. The schema below lists every field. ```bash cURL theme={null} curl https://api.stophy.dev/v1/batch/scrape/{id}/errors \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/batch/scrape/{id}/errors", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/batch/scrape/{id}/errors", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` # Batch scrape status Source: https://docs.stophy.dev/api-reference/endpoint/batch-scrape-status api-reference/openapi.json GET /v1/batch/scrape/{id} Check a batch scrape and read the finished pages. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. ## Pages Poll until `status` is `completed`, then call `next` until it is gone. Each answer holds up to 100 finished pages. A page's address is in `metadata.url`. See [Page through results](/guides/paging). `failed` counts the pages that could not be read. `errors` lists the failed pages in this answer with `url`, `code`, `message`, `retryable` and `at`, and `error` is set only when the whole job failed. For every failed page, call [Batch scrape errors](/api-reference/endpoint/batch-scrape-errors). ```bash cURL theme={null} curl https://api.stophy.dev/v1/batch/scrape/job_385XD5MMpQfsXsGFdTO9vQ \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/batch/scrape/job_385XD5MMpQfsXsGFdTO9vQ", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/batch/scrape/job_385XD5MMpQfsXsGFdTO9vQ", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "status": "completed", "total": 2, "completed": 2, "creditsUsed": 1, "createdAt": "2026-11-05T23:35:30.889Z", "completedAt": "2026-11-05T23:35:32.943Z", "duration": 2.054, "expiresAt": "2026-11-06T23:35:30.889Z", "data": [ { "markdown": "# bunfig.toml\n\nConfigure Bun's behavior using its configuration file bunfig.toml\n\n`bunfig.toml` is Bun's configuration…", "metadata": { "viewport": "width=device-width, initial-scale=1", "theme-color": [ "#ffffff", "#0d0a0c" ], "og:type": "website", "og:image": "https://bun.com/og/docs/runtime/bunfig.png", "twitter:site": "@bunjavascript", "twitter:card": "summary_large_image", "ogTitle": "bunfig.toml | Bun Docs", "ogDescription": "Configure Bun's behavior using its configuration file bunfig.toml", "ogUrl": "https://bun.com/docs/runtime/bunfig", "ogLocale": "en_US", "ogSiteName": "Bun", "favicon": "https://bun.com/favicon.ico", "title": "bunfig.toml | Bun Docs", "description": "Configure Bun's behavior using its configuration file bunfig.toml", "language": "en", "ogImage": "https://bun.com/og/docs/runtime/bunfig.png", "sourceURL": "https://bun.com/docs/runtime/bunfig", "url": "https://bun.com/docs/runtime/bunfig", "statusCode": 200, "contentType": "text/html", "cacheState": "hit", "cachedAt": "2026-11-05T19:33:09.837Z", "scrapeId": "job_385XD5MMpQfsXsGFdTO9vQ", "creditsUsed": 0 } } ] } ``` # Browser task Source: https://docs.stophy.dev/api-reference/endpoint/browser-task api-reference/openapi.json POST /v1/browser/task Click through a public website in a real browser to search, filter or fill a form. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Best for a few steps a person would click through on a public site, like a search with filters or a form to fill without sending it. It answers at once with an id; ask browser.task.status for the result. A task takes up to 20 steps and 3 minutes, and stops before anything that pays, books, sends, submits or deletes. Stophy never logs in to a site. ## Price 3 credits for each step the task takes, up to maxSteps and maxCost. A task that ends before its first step costs nothing. Starting a task sets aside the most it can cost, and what it does not use comes back when it ends. See [Pricing](/billing) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/browser/task \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://news.ycombinator.com","goal":"Open the newest stories and read the title of the first one","schema":{"type":"object","properties":{"title":{"type":"string"}}},"maxSteps":4}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/browser/task", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://news.ycombinator.com", goal: "Open the newest stories and read the title of the first one", schema: { type: "object", properties: { title: { type: "string" } } }, maxSteps: 4, }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/browser/task", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://news.ycombinator.com", "goal": "Open the newest stories and read the title of the first one", "schema": { "type": "object", "properties": {"title": {"type": "string"}}, }, "maxSteps": 4, }, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "id": "7c76df71-1d78-4d05-b09c-2f7840b12400", "status": "running" }, "creditsUsed": 0, "requestId": "3e29cc22-93d3-4b70-ac60-52c18b07ca4f" } ``` # Browser task status Source: https://docs.stophy.dev/api-reference/endpoint/browser-task-status api-reference/openapi.json POST /v1/browser/task/status Check a browser task and read its result. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. result is null while the task runs. When it ends, result says whether the goal was met, why it stopped if not, and the steps taken. A task is kept for 24 hours. Free. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/browser/task/status \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"id":"7c76df71-1d78-4d05-b09c-2f7840b12400"}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/browser/task/status", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ id: "7c76df71-1d78-4d05-b09c-2f7840b12400" }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/browser/task/status", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={"id": "7c76df71-1d78-4d05-b09c-2f7840b12400"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "status": "done", "result": { "done": false, "reason": "The browser could not run this task. Nothing was charged." }, "creditsUsed": 0 }, "creditsUsed": 0, "requestId": "742fd075-3678-4a8a-a92f-7b13eccb9209" } ``` # Crawl Source: https://docs.stophy.dev/api-reference/endpoint/crawl api-reference/openapi.json POST /v1/crawl Crawl a website in the background. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. Best for reading a whole section of a site without holding a call open. It answers at once with an id; ask crawl.status for the pages, or send webhook to be told as each one finishes. ## Price 1 credit a page, however it is reached. json with a schema or a prompt, summary and highlights add 4 credits each when they return something. CSS rules and attributes add nothing. A PDF adds 1 credit for each page read. Each perform action adds 2 credits. An answer from a stored copy within maxAge is free. A page that comes back with a 404 or 410 status is charged like any page. A page that cannot be read costs nothing. Each page is charged when it finishes. Starting the job is free. See [Pricing](/billing) for what credits cost. ## Limits An account runs up to 5 crawls and batch scrapes at once. A sixth start answers 400 `invalidRequest`: `jobs: you already have 5 jobs running. Wait for one of them to finish, then try again.` Wait until one is `completed`, then start it again. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/crawl \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com/docs","limit":2}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/crawl", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://bun.com/docs", limit: 2 }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/crawl", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={"url": "https://bun.com/docs", "limit": 2}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "id": "job_a-Bqc0NaZ8ADzLB4rhpeKA", "url": "https://api.stophy.dev/v1/crawl/job_a-Bqc0NaZ8ADzLB4rhpeKA" } ``` # Cancel a crawl Source: https://docs.stophy.dev/api-reference/endpoint/crawl-cancel api-reference/openapi.json DELETE /v1/crawl/{id} Stop a background crawl and keep the pages already read. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. ```bash cURL theme={null} curl -X DELETE https://api.stophy.dev/v1/crawl/job_LcaBuaAN-S2yX7jXmsgWTw \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/crawl/job_LcaBuaAN-S2yX7jXmsgWTw", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.delete( "https://api.stophy.dev/v1/crawl/job_LcaBuaAN-S2yX7jXmsgWTw", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "status": "cancelled" } ``` # Crawl errors Source: https://docs.stophy.dev/api-reference/endpoint/crawl-errors api-reference/openapi.json GET /v1/crawl/{id}/errors List the pages a background crawl could not read, and why. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. ## Failed pages Lists every page the job could not read, up to 1,000, each with `url`, `code`, `message`, `retryable` and `at`. `isTruncated` is `true` when there are more. Retry a page when `retryable` is `true`. > [!WARNING] > > No example is recorded. The schema below lists every field. ```bash cURL theme={null} curl https://api.stophy.dev/v1/crawl/{id}/errors \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/crawl/{id}/errors", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/crawl/{id}/errors", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` # Crawl status Source: https://docs.stophy.dev/api-reference/endpoint/crawl-status api-reference/openapi.json GET /v1/crawl/{id} Check a background crawl and read the finished pages. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. ## Pages Poll until `status` is `completed`, then call `next` until it is gone. Each answer holds up to 100 finished pages. A page's address is in `metadata.url`. See [Page through results](/guides/paging). `failed` counts the pages that could not be read. `errors` lists the failed pages in this answer with `url`, `code`, `message`, `retryable` and `at`, and `error` is set only when the whole job failed. For every failed page, call [Crawl errors](/api-reference/endpoint/crawl-errors). ```bash cURL theme={null} curl https://api.stophy.dev/v1/crawl/job_a-Bqc0NaZ8ADzLB4rhpeKA \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/crawl/job_a-Bqc0NaZ8ADzLB4rhpeKA", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/crawl/job_a-Bqc0NaZ8ADzLB4rhpeKA", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "status": "completed", "total": 2, "completed": 2, "creditsUsed": 2, "createdAt": "2026-11-05T23:35:26.793Z", "completedAt": "2026-11-05T23:35:28.779Z", "duration": 1.986, "expiresAt": "2026-11-06T23:35:26.793Z", "data": [ { "markdown": "# Welcome to Bun\n\nBun is an all-in-one toolkit for developing modern JavaScript/TypeScript applications.\n\n[Bun Runtime…", "metadata": { "viewport": "width=device-width, initial-scale=1", "theme-color": [ "#ffffff", "#0d0a0c" ], "og:type": "website", "og:image": "https://bun.com/og/docs.png", "twitter:site": "@bunjavascript", "twitter:card": "summary_large_image", "ogTitle": "Welcome to Bun | Bun Docs", "ogDescription": "Bun is an all-in-one toolkit for developing modern JavaScript/TypeScript applications.", "ogUrl": "https://bun.com/docs", "ogLocale": "en_US", "ogSiteName": "Bun", "favicon": "https://bun.com/favicon.ico", "title": "Welcome to Bun | Bun Docs", "description": "Bun is an all-in-one toolkit for developing modern JavaScript/TypeScript applications.", "language": "en", "ogImage": "https://bun.com/og/docs.png", "sourceURL": "https://bun.com/docs", "url": "https://bun.com/docs", "statusCode": 200, "contentType": "text/html", "cacheState": "miss", "scrapeId": "job_a-Bqc0NaZ8ADzLB4rhpeKA", "creditsUsed": 1 } } ] } ``` # Extract Source: https://docs.stophy.dev/api-reference/endpoint/extract api-reference/openapi.json POST /v1/extract Pull the fields you name from any public page as JSON, each checked against the page. Send one request and get JSON back. Best for a few facts from one page, like a price, a date or a list of names. Every field is checked against the page text and comes back null when the page does not state it. Use scrape for the whole page. ## Price 5 credits for most pages: the page's own price plus 4 credits. A call that finds none of the fields is free. See [Pricing](/billing) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/extract \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"urls":["https://bun.com/docs/runtime/bunfig"],"schema":{"type":"object","properties":{"file":{"type":"string"}}},"prompt":"What is the name of the configuration file this page describes?"}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/extract", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ urls: ["https://bun.com/docs/runtime/bunfig"], schema: { type: "object", properties: { file: { type: "string" } } }, prompt: "What is the name of the configuration file this page describes?", }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/extract", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "urls": ["https://bun.com/docs/runtime/bunfig"], "schema": { "type": "object", "properties": {"file": {"type": "string"}}, }, "prompt": "What is the name of the configuration file this page describes?", }, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "id": "860b5104-c8fc-4a85-aff9-f826b15c5770", "invalidURLs": [] } ``` # Extract result Source: https://docs.stophy.dev/api-reference/endpoint/extract-result api-reference/openapi.json GET /v1/extract/{id} Read what an extract found. Results are kept for 24 hours. Send one request and get JSON back. Examples in cURL, TypeScript and Python. ```bash cURL theme={null} curl https://api.stophy.dev/v1/extract/860b5104-c8fc-4a85-aff9-f826b15c5770 \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/extract/860b5104-c8fc-4a85-aff9-f826b15c5770", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/extract/860b5104-c8fc-4a85-aff9-f826b15c5770", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "status": "completed", "data": { "file": "bunfig.toml" }, "confidence": { "file": 0.9432 }, "expiresAt": "2026-11-06T23:35:37.867Z" } ``` # Limits Source: https://docs.stophy.dev/api-reference/endpoint/limits api-reference/openapi.json GET /v1/limits See your plan, balance, rate limit and key expiry. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Free. Counts as one call toward the per-minute rate limit. Needs an API key: without one the answer is 401, and the keyless limits are 10 requests a minute and 50 a day per IP. ```bash cURL theme={null} curl https://api.stophy.dev/v1/limits \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/limits", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/limits", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "tier": "paid", "balanceCredits": 5000, "rateLimit": { "limitPerMinute": 600, "remaining": 596, "resetsAt": "2026-11-05T23:37:00.000Z" }, "keyExpiresAt": null, "billingUrl": "https://stophy.dev/billing" }, "creditsUsed": 0, "requestId": "6d66e7cf-66c5-406e-b382-536aedbd026a" } ``` # List parsers Source: https://docs.stophy.dev/api-reference/endpoint/list-parsers api-reference/openapi.json GET /v1/parsers List the parsers: the sites scrape can return as JSON, the page each one reads, what it returns and what it costs. Send one request and get JSON back. > [!NOTE] > > Needs no API key. ```bash cURL theme={null} curl https://api.stophy.dev/v1/parsers ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/parsers"); console.log(await response.json()); ``` ```python Python theme={null} import requests response = requests.get( "https://api.stophy.dev/v1/parsers", ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "parsers": [ { "name": "google-maps", "takes": "A Google Maps search page that names a place after in, near or around", "example": "https://www.google.com/maps/search/dentists+in+Ljubljana", "view": null, "response": { "results": [ { "id": "0x47653296b2abdbc7:0x49588016d0bf3f31", "url": "https://www.google.com/maps?cid=5285114998199107377", "name": "OrthoDental", "categories": [ "Dentist", "Dental clinic", "Dental implants periodontist" ], "address": "Vilharjeva cesta 42, 1000 Ljubljana, Slovenia", "location": { "latitude": 46.0595907, "longitude": 14.5190697 }, "phone": "+1 555 0100", "website": "https://orthodental.si/", "description": null, "rating": 4.9, "reviewCount": 845, "priceLevel": null, "hours": [ { "days": "Thursday", "times": [ "7 AM-8 PM" ] } ], "images": [ "https://lh3.googleusercontent.com/grass-cs/AABkmLdBhaKXYHqK_5Aj1bnahBGOIT1sRrAAJnXe3Rmn96rrVp4oGovG0IIlCy2N9ZA74ppszS7_…" ], "googlePlaceId": "ChIJx9urspYyZUcRMT-_0BaAWEk", "photos": 57, "hoursToday": "7 AM-8 PM", "openStatus": "Closed · Opens 7 AM", "timezone": "Europe/Ljubljana", "reservationUrl": null, "attributes": [ "Wheelchair accessible entrance", "Wheelchair accessible parking lot", "Wheelchair accessible restroom" ] } ], "cursor": null, "page": 1, "total": null }, "options": [ { "name": "minRating" } ], "output": "place list", "returns": [ "results", "cursor", "page" ], "price": "1 credit per call", "credits": 1, "keyless": true } ], "kinds": { "post": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "anyOf": [ { "type": "string" } ] }, "text": { "anyOf": [ { "type": "string" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } ] }, "community": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "name", "url" ], "additionalProperties": {} } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "likes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "comments": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "shares": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "views": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": {} } }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "url", "title" ], "additionalProperties": {} }, "profile": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "bio": { "anyOf": [ { "type": "string" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "isVerified": { "anyOf": [ { "type": "boolean" } ] }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "posts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "website": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "location": { "anyOf": [ { "type": "string" } ] }, "category": { "anyOf": [ { "type": "string" } ] } }, "required": [ "id", "url", "handle" ], "additionalProperties": {} }, "product": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "anyOf": [ { "type": "string" } ] }, "brand": { "anyOf": [ { "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount", "currency" ], "additionalProperties": {} } ] }, "originalPrice": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount", "currency" ], "additionalProperties": {} } ] }, "rating": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 5 } ] }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "availability": { "anyOf": [ { "type": "string" } ] }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "categories": { "type": "array", "items": { "type": "string" } }, "seller": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } ] } }, "required": [ "id", "url", "title" ], "additionalProperties": {} }, "place": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "name": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "address": { "anyOf": [ { "type": "string" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ], "additionalProperties": {} } ] }, "phone": { "anyOf": [ { "type": "string" } ] }, "website": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "description": { "anyOf": [ { "type": "string" } ] }, "rating": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 5 } ] }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceLevel": { "anyOf": [ { "type": "string" } ] }, "hours": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "string" }, "times": { "type": "array", "items": { "type": "string" } } }, "required": [ "days", "times" ], "additionalProperties": {} } }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "id", "url", "name" ], "additionalProperties": {} }, "review": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } ] }, "rating": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 5 } ] }, "title": { "anyOf": [ { "type": "string" } ] }, "text": { "anyOf": [ { "type": "string" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "likes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] } }, "required": [ "text", "publishedAt" ], "additionalProperties": {} } ] }, "subject": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "url" ], "additionalProperties": false } ] } }, "required": [ "id", "url", "author" ], "additionalProperties": {} }, "job": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "company": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "url" ], "additionalProperties": false } ] }, "location": { "anyOf": [ { "type": "string" } ] }, "isRemote": { "anyOf": [ { "type": "boolean" } ] }, "salary": { "anyOf": [ { "type": "object", "properties": { "min": { "anyOf": [ { "type": "number" } ] }, "max": { "anyOf": [ { "type": "number" } ] }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 } ] }, "period": { "anyOf": [ { "type": "string", "enum": [ "hour", "day", "week" ] } ] } }, "required": [ "min", "max", "currency" ], "additionalProperties": {} } ] }, "employmentType": { "anyOf": [ { "type": "string" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "description": { "anyOf": [ { "type": "string" } ] } }, "required": [ "id", "url", "title" ], "additionalProperties": {} }, "listing": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "anyOf": [ { "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount", "currency" ], "additionalProperties": {} } ] }, "pricePeriod": { "anyOf": [ { "type": "string", "enum": [ "sale", "night", "month" ] } ] }, "status": { "anyOf": [ { "type": "string" } ] }, "address": { "anyOf": [ { "type": "string" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ], "additionalProperties": {} } ] }, "bedrooms": { "anyOf": [ { "type": "number" } ] }, "bathrooms": { "anyOf": [ { "type": "number" } ] }, "area": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "unit": { "type": "string", "enum": [ "sqft", "sqm" ] } }, "required": [ "amount", "unit" ], "additionalProperties": {} } ] }, "propertyType": { "anyOf": [ { "type": "string" } ] }, "rating": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 5 } ] }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "host": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } ] } }, "required": [ "id", "url", "title" ], "additionalProperties": {} }, "video": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "anyOf": [ { "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "durationSeconds": { "anyOf": [ { "type": "number", "minimum": 0 } ] }, "views": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "likes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "comments": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "thumbnailUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "url", "title" ], "additionalProperties": {} }, "comment": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } ] }, "text": { "anyOf": [ { "type": "string" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "likes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "parentId": { "anyOf": [ { "type": "string" } ] } }, "required": [ "id", "url", "author" ], "additionalProperties": {} }, "event": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "anyOf": [ { "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1…" } ] }, "timezone": { "anyOf": [ { "type": "string" } ] }, "isOnline": { "anyOf": [ { "type": "boolean" } ] }, "address": { "anyOf": [ { "type": "string" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "latitude", "longitude" ], "additionalProperties": {} } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "amount", "currency" ], "additionalProperties": {} } ] }, "hosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" } ] }, "name": { "anyOf": [ { "type": "string" } ] }, "handle": { "anyOf": [ { "type": "string" } ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" } ] }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" } ] } }, "required": [ "id", "name", "handle" ], "additionalProperties": {} } }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "id", "url", "title" ], "additionalProperties": {} } } } } ``` # Logs Source: https://docs.stophy.dev/api-reference/endpoint/logs api-reference/openapi.json GET /v1/logs List your recent calls, 50 per page. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. Free. ```bash cURL theme={null} curl https://api.stophy.dev/v1/logs \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/logs", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/logs", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "endpoints": [ "search", "scrape", "extract" ], "logs": [ { "apiKeyId": "", "apiKeyName": "My key", "createdAt": "2026-11-05T23:35:35.272Z", "credits": 5, "durationMs": null, "endpoint": "extract", "id": "8be659e2-a763-4e67-b8ac-e9eb53b89e4d", "method": "POST", "requestId": "b3b7fe02-9cf2-4339-b7f8-aa9e034be26f", "response": "success", "status": 200 } ], "page": 0, "pageSize": 50, "total": 85, "totalPages": 2 } ``` # Map Source: https://docs.stophy.dev/api-reference/endpoint/map api-reference/openapi.json POST /v1/map Scrape the list of pages on a website. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. Best for finding the right page on a site before reading it with scrape. Add search to rank pages about one topic first. > [!NOTE] > > Works without an API key, up to 10 calls a minute and 50 a day per IP. See [Rate limits](/rate-limits). ## Price 1 credit per call. See [Pricing](/billing) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/map \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com","search":"sqlite"}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/map", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://bun.com", search: "sqlite" }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/map", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={"url": "https://bun.com", "search": "sqlite"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "links": [ { "url": "https://bun.com/reference/node/sqlite/constants/SQLITE_ANALYZE" } ] } ``` # Parse Source: https://docs.stophy.dev/api-reference/endpoint/parse api-reference/openapi.json POST /v1/parse Turn a PDF, Word, Excel, PowerPoint or HTML file into markdown. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Best for a file you already hold. To read a page or a PDF by its address, use scrape. > [!NOTE] > > Works without an API key, up to 10 calls a minute and 50 a day per IP. See [Rate limits](/rate-limits). ## Price 1 credit per call. See [Pricing](/billing) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/parse \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"file":"PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=","filename":"tides.html"}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/parse", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ file: "PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=", filename: "tides.html", }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/parse", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "file": "PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=", "filename": "tides.html", }, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "markdown": "# How tides work\n\nThe Moon pulls on the oceans and makes two bulges of water that move around the Earth as it turns,…", "metadata": { "title": "How tides work", "contentType": "text/html" } } } ``` # Collect the key Source: https://docs.stophy.dev/api-reference/endpoint/poll-sign-up api-reference/openapi.json POST /v1/signup/poll Collect the key once your person approves. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. > [!NOTE] > > Needs no API key. Free, and needs no key. Answers 202 with status waiting until your person approves, so poll every few seconds. After approval it answers 200 with the key exactly once. A code that is unknown, expired or already collected is notFound: sign up again. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/signup/poll \ -H "Content-Type: application/json" \ -d '{"code":""}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/signup/poll", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ code: "" }), }); console.log(await response.json()); ``` ```python Python theme={null} import requests response = requests.post( "https://api.stophy.dev/v1/signup/poll", json={"code": ""}, ) print(response.json()) ``` ```json 202 theme={null} { "success": true, "data": { "status": "waiting", "claimUrl": "" }, "creditsUsed": 0, "requestId": "f178fb12-7986-4688-a700-915024faa1b9" } ``` # Revoke your key Source: https://docs.stophy.dev/api-reference/endpoint/revoke-key api-reference/openapi.json DELETE /v1/key Revoke the key you are calling with. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. Free. The key stops working at once. Needs an API key, not a signed-in session. > [!WARNING] > > Calling it would revoke the key that recorded these examples. ```bash cURL theme={null} curl -X DELETE https://api.stophy.dev/v1/key \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/key", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.delete( "https://api.stophy.dev/v1/key", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` # Scrape Source: https://docs.stophy.dev/api-reference/endpoint/scrape api-reference/openapi.json POST /v1/scrape Scrape any public web page as markdown, HTML, links, a screenshot or JSON. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Best for reading a page as markdown, HTML, links or a screenshot. The page runs its JavaScript before it is read. Without formats you get markdown. Send formats as names, \["markdown","links"], or as objects, `[{"type":"screenshot","fullPage":true}]`, or mix them. For a site's own structured data (video, social, places, shopping, jobs, homes) send formats `[{"type":"json","parser":""}]`; GET /v1/parsers lists the parsers. A YouTube video link comes back as its title, channel, date, length, views, likes and description. > [!NOTE] > > Works without an API key, up to 10 calls a minute and 50 a day per IP. See [Rate limits](/rate-limits). ## Price 1 credit for any page, however it is reached. json with a schema or a prompt, summary and highlights add 4 credits each when they return something. CSS rules and attributes add nothing. A PDF adds 1 credit for each page read. Each perform action adds 2 credits. An answer from a stored copy within maxAge is free. A page that comes back with a 404 or 410 status is charged like any page. A page that cannot be read costs nothing. Each page of a urls call is priced on its own. creditsUsed shows what the call cost. See [Pricing](/billing) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com/docs/runtime/bunfig"}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://bun.com/docs/runtime/bunfig" }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={"url": "https://bun.com/docs/runtime/bunfig"}, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "markdown": "# bunfig.toml\n\nConfigure Bun's behavior using its configuration file bunfig.toml\n\n`bunfig.toml` is Bun's configuration…", "metadata": { "viewport": "width=device-width, initial-scale=1", "theme-color": [ "#ffffff", "#0d0a0c" ], "og:type": "website", "og:image": "https://bun.com/og/docs/runtime/bunfig.png", "twitter:site": "@bunjavascript", "twitter:card": "summary_large_image", "ogTitle": "bunfig.toml | Bun Docs", "ogDescription": "Configure Bun's behavior using its configuration file bunfig.toml", "ogUrl": "https://bun.com/docs/runtime/bunfig", "ogLocale": "en_US", "ogSiteName": "Bun", "favicon": "https://bun.com/favicon.ico", "title": "bunfig.toml | Bun Docs", "description": "Configure Bun's behavior using its configuration file bunfig.toml", "language": "en", "ogImage": "https://bun.com/og/docs/runtime/bunfig.png", "sourceURL": "https://bun.com/docs/runtime/bunfig", "url": "https://bun.com/docs/runtime/bunfig", "statusCode": 200, "contentType": "text/html", "cacheState": "hit", "cachedAt": "2026-11-05T19:33:09.837Z", "scrapeId": "f82a75f2-1f53-4abb-ac5a-9fdbc4314549", "creditsUsed": 0 } }, "creditsUsed": 0 } ``` # Search Source: https://docs.stophy.dev/api-reference/endpoint/search api-reference/openapi.json POST /v1/search Search the web, news, images, scholarly papers, companies and people in one call. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Best when you want web results, news, images or all three at once, grouped by type, with the page text of the top web results if you ask for it. Send categories research for scholarly papers with authors, venue and citation counts, companies for company profiles filtered by place, industry, size and founding year, people for people by role, company, place or research topic, or developer for passages from GitHub issues, pull requests, releases, READMEs, developer docs and API operations. > [!NOTE] > > Works without an API key, up to 10 calls a minute and 50 a day per IP. See [Rate limits](/rate-limits). ## Price 2 credits per 10 results from each source and each research, companies, people or developer list, plus 1 credit for each web result that comes back with its page text when scrapeOptions is on. See [Pricing](/billing) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/search \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"nvidia earnings","sources":["web","news"],"limit":5}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "nvidia earnings", sources: ["web", "news"], limit: 5, }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/search", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "query": "nvidia earnings", "sources": ["web", "news"], "limit": 5, }, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "news": [ { "title": "Stocks making the biggest moves midday: Micron, Tesla, Tripadvisor, AppLovin, Nvidia & more", "url": "https://www.cnbc.com/2026/11/05/stocks-making-the-biggest-moves-midday-mu-tsla-trip-app-nvda.html", "snippet": "Here are some of the companies making headlines in midday trading.", "date": "2026-11-05T18:35:11.000Z", "position": 1 } ], "web": [ { "url": "https://nvidianews.nvidia.com/news/nvidia-announces-financial-results-for-second-quarter-fiscal-2027", "title": "NVIDIA Announces Financial Results for Second Quarter Fiscal ...", "description": "GAAP and non-GAAP earnings per diluted share were $2.46 and $2.22, respectively.\n\n“AI has reached its inflection…", "position": 1 } ] }, "creditsUsed": 4 } ``` # Sign up Source: https://docs.stophy.dev/api-reference/endpoint/sign-up api-reference/openapi.json POST /v1/signup Ask your person to approve a Stophy account for you. Send one request and get JSON back. Examples in cURL, TypeScript and Python. > [!NOTE] > > Needs no API key. Free, and needs no key. Returns a claimUrl for your person and a secret code. Your person signs in with GitHub or Google and approves. A new account starts with 5,000 free credits. Then send the code to POST /v1/signup/poll to collect the key. Each IP address can sign up a few times a day, then the answer is rateLimited with retryAfterSeconds. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/signup ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/signup", { method: "POST", }); console.log(await response.json()); ``` ```python Python theme={null} import requests response = requests.post( "https://api.stophy.dev/v1/signup", ) print(response.json()) ``` ```json 201 theme={null} { "success": true, "data": { "claimUrl": "", "code": "", "expiresAt": "2026-11-06T23:36:07.172Z" }, "creditsUsed": 0, "requestId": "23ad30a8-6558-49cf-9c85-960f97d273a1" } ``` # Usage Source: https://docs.stophy.dev/api-reference/endpoint/usage api-reference/openapi.json GET /v1/usage See your balance and what you have used. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing. Free. Your balance in credits is `balanceCredits` on [Limits](/api-reference/endpoint/limits). `balanceMicros` stays for older clients. ```bash cURL theme={null} curl https://api.stophy.dev/v1/usage \ -H "Authorization: Bearer $STOPHY_API_KEY" ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/usage", { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, }, }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.stophy.dev/v1/usage", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, ) print(response.json()) ``` ```json 200 theme={null} { "balanceMicros": 10000000, "creditsUsed": 120, "requestCount": 85 } ``` # Errors Source: https://docs.stophy.dev/api-reference/errors Every Stophy error comes back as success false, error and code. Here is each code, its HTTP status and whether to retry. A failed call costs nothing. Send a field the endpoint does not take and read the error. ```bash theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com","colour":"red"}' ``` > [accordion] Response > > The status is `400`. The list of fields is cut. > > ```json theme={null} > { > "success": false, > "error": "Unknown field `colour`. Fields: url, formats, onlyMainContent, onlyCleanContent, includeTags, excludeTags, maxAge, …", > "code": "invalidRequest" > } > ``` Every error has this flat shape. | Field | What it is | | - | - | | `success` | Always `false`. | | `error` | What went wrong and what to do next, in plain words. | | `code` | A stable code from the table below. | | `retryAfterSeconds` | Present when you should wait a set time. The `Retry-After` header has the same value. When it is absent, back off as [Errors and retries](/guides/errors-and-retries) says. | | `signupUrl` | Present on `apiKeyRequired`, `freeLimit` and a key that is not valid. Where a person gets a key. | | `signup` | Sent next to `signupUrl`: `POST https://api.stophy.dev/v1/signup`, the call that gets an agent a key. See [Sign up](/api-reference/endpoint/sign-up). | The `X-Request-ID` header names the request. Include it when you contact support. ## Error codes | Code | Status | Retry | What it means | | - | - | - | - | | `invalidRequest` | 400 | No | The input is not valid. The error names the field. | | `apiKeyRequired` | 401 | No | This call needs an API key: the endpoint, paging or a field you sent. | | `unauthorized` | 401 | No | The API key is not valid or has expired. | | `insufficientCredits` | 402 | No | Your balance is too low for this call, and nothing was charged. The `x-required-credits` and `x-available-credits` headers say by how much. [Top up](/billing). | | `forbidden` | 403 | No | This needs the Stophy dashboard. Sign in at stophy.dev and make the change there. | | `siteNotRead` | 403 | No | Stophy does not read this site as a page. Use a [parser](/guides/parsers). | | `notFound` | 404 | No | The endpoint, the page or the job does not exist. | | `methodNotAllowed` | 405 | No | The path takes another method. The `Allow` header names it. | | `jobFinished` | 409 | No | The crawl or batch scrape already ended, so there is nothing to cancel. | | `profileBusy` | 409 | No | Another call is using this browser profile. | | `payloadTooLarge` | 413 | No | The request body is too large. | | `profileTooLarge` | 413 | No | The browser profile is too large to save. | | `unsupportedMediaType` | 415 | No | Send the body as JSON with `Content-Type: application/json`. | | `freeLimit` | 429 | Yes | You used the free calls without a key. Get a key at `signupUrl`, or wait `retryAfterSeconds`. | | `rateLimited` | 429 | Yes | Too many requests. Wait `retryAfterSeconds`. | | `internalError` | 500, 503 | Yes | That one is on us, and it cost nothing. Retry in a second. If it fails again, send support the `X-Request-ID`. | | `sourceChanged` | 502 | No | The site answered in a shape Stophy could not read. Retrying will not help yet. | | `sourceUnavailable` | 503 | Yes | The site is not answering right now. Wait `retryAfterSeconds`. | | `sourceRefused` | 503 | Yes | The site is refusing requests right now. Wait `retryAfterSeconds`. | | `sourceTimeout` | 504 | Yes | The site took too long to answer. Try again. | ## Real errors **No key on an endpoint that needs one.** `401 apiKeyRequired`, from crawl. ```json theme={null} { "success": false, "error": "This needs an API key. POST https://api.stophy.dev/v1/signup returns a claim link for your person to approve and a code that collects the key. Send it as Authorization: Bearer .", "code": "apiKeyRequired", "signupUrl": "https://stophy.dev/signup", "signup": "POST https://api.stophy.dev/v1/signup" } ``` **A key that is not valid.** `401 unauthorized`. ```json theme={null} { "success": false, "error": "This API key is not valid or has expired. POST https://api.stophy.dev/v1/signup returns a claim link for your person to approve and a code that collects the key. Send it as Authorization: Bearer .", "code": "unauthorized", "signupUrl": "https://stophy.dev/signup", "signup": "POST https://api.stophy.dev/v1/signup" } ``` **A path that is not an endpoint.** `404 notFound`, from a removed path like `/v1/google/search`. ```json theme={null} { "success": false, "error": "No endpoint at this path. See every endpoint at https://api.stophy.dev/openapi.json", "code": "notFound" } ``` **A domain with no website.** `404 notFound`, from scrape. ```json theme={null} { "success": false, "error": "That address has no website behind it. Check the spelling of the domain, then try again.", "code": "notFound" } ``` ## Account codes These come from signing in to the CLI and from invites, not from a data endpoint. | Code | Status | What it means | | - | - | - | | `invalidCliSession` | 400 | The sign-in session is not valid. | | `invalidCliVerifier` | 400 | The sign-in verifier is not valid. | | `cliSessionNotFound` | 404 | The sign-in session was not found or has expired. | | `cliSessionExists` | 409 | The sign-in session already exists. | | `cliSessionCompleted` | 409 | The sign-in session is no longer pending. | | `inviteClaimed` | 409 | You already claimed this invite. | | `inviteDisabled` | 410 | This invite link was turned off. | | `inviteExpired` | 410 | This invite link has expired. | | `inviteUsedUp` | 410 | This invite link has been used up. | ## Retrying Retry only the codes marked Yes. [Errors and retries](/guides/errors-and-retries) has the wait and the most tries for each code, and a retry loop for TypeScript and Python. # Introduction Source: https://docs.stophy.dev/api-reference/introduction Send JSON to one base URL with a bearer key. Search, scrape, map, crawl, batch scrape, extract and parse, and read 103 sites as JSON through parsers. ## Base URL ```text theme={null} https://api.stophy.dev ``` | Endpoint | What it does | | - | - | | [`POST /v1/search`](/api-reference/endpoint/search) | Searches the web, news and images | | [`POST /v1/scrape`](/api-reference/endpoint/scrape) | Reads one page as markdown, HTML, links, a screenshot or JSON | | [`POST /v1/map`](/api-reference/endpoint/map) | Lists the pages on a site | | [`POST /v1/parse`](/api-reference/endpoint/parse) | Turns a PDF, Word, Excel, PowerPoint or HTML file into markdown | | [`POST /v1/crawl`](/api-reference/endpoint/crawl) | Crawls a site in the background | | [`POST /v1/batch/scrape`](/api-reference/endpoint/batch-scrape) | Scrapes many pages in the background | | [`POST /v1/extract`](/api-reference/endpoint/extract) | Pulls the fields you name from pages | | [`POST /v1/browser/task`](/api-reference/endpoint/browser-task) | Clicks through a site in a real browser | A site's own data, like a Reddit search or a YouTube transcript, comes from scrape with a [parser](/guides/parsers). A field an endpoint does not take returns `400`. ## Authentication Create a key at [stophy.dev/signup](https://stophy.dev/signup) and send it as a bearer token. ```bash theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com/docs/runtime/bunfig"}' ``` With no key, the endpoints that need one return `401` with code `apiKeyRequired`, a `signupUrl` for a person and a `signup` call for an agent. Search, scrape, map and parse also work without a key, within the [free limits](/rate-limits). ## Responses Each endpoint answers in its own shape, and each endpoint's page shows a real response. Search returns `success`, `data` and `creditsUsed`: ```json theme={null} { "success": true, "data": { "web": [ { "url": "https://nvidianews.nvidia.com/news/nvidia-announces-financial-results-for-second-quarter-fiscal-2027", "title": "NVIDIA Announces Financial Results for Second Quarter Fiscal ...", "position": 1 } ] }, "creditsUsed": 4 } ``` Scrape and parse put the page in `data`, and scrape puts its cost in `data.metadata.creditsUsed`. Map returns `links`. Crawl, batch scrape and extract return a job `id`, and their status calls return `status`, the pages or fields in `data`, and `creditsUsed`. The account calls add `requestId`. Empty values are left out. Every response has an `X-Request-ID` header and an `x-credits-used` header. To cut long text, add `?maxTextLength=` to the URL: longer text ends with `…`. A failed call returns an error status and a flat body: `{ "success": false, "error": "", "code": "" }`. See [Errors](/api-reference/errors). ## Cost `creditsUsed` is what the call cost in credits. Most calls cost 1 credit, and a call that fails costs nothing. See [Pricing](/billing). # Pricing Source: https://docs.stophy.dev/billing Most Stophy calls cost 1 credit. Search costs 2 credits per 10 results. New accounts start with 5,000 free credits, and a failed call costs nothing. ## Credits Every call is priced in credits, and most calls cost 1 credit. Your account starts with 5,000 free credits, with no card. `creditsUsed` in each response is what the call cost. ## Buy credits Top up at [stophy.dev](https://stophy.dev/billing), from $10 to $10,000 at a time. Credits cost less once your top-ups reach $100, $500 and \$2,000: | Your top-ups so far | 1,000 credits cost | | - | - | | Less than \$100 | \$2.00 | | \$100 or more | \$1.50 | | \$500 or more | \$1.20 | | \$2,000 or more | \$0.90 | A first \$10 top-up buys 5,000 credits. Your credits never expire. ## What a call costs Each endpoint's [reference page](/api-reference/introduction) shows its price. | Endpoint | Price | | - | - | | [Search](/api-reference/endpoint/search) | 2 credits per 10 results from each source, plus 1 credit for each web result that comes back with its page text when `scrapeOptions` is on | | [Scrape](/api-reference/endpoint/scrape) | 1 credit for any page. `json` with a schema or a prompt, `summary` and `highlights` add 4 credits each when they return something. A PDF adds 1 credit for each page read. Each action adds 2 credits. | | [Map](/api-reference/endpoint/map) | 1 credit per call | | [Parse](/api-reference/endpoint/parse) | 1 credit per call | | [Crawl](/api-reference/endpoint/crawl) | 1 credit a page. Starting the job is free. | | [Batch scrape](/api-reference/endpoint/batch-scrape) | Each page costs what scrape would. Starting the job is free. | | [Extract](/api-reference/endpoint/extract) | 5 credits for most pages: the page's own price plus 4 credits. A call that finds none of the fields is free. | | [Browser task](/api-reference/endpoint/browser-task) | 3 credits for each step the task takes, up to `maxSteps` and `maxCost` | | Status, cancel, catalog and account calls | Free | A page that cannot be read costs nothing. A page that comes back with a 404 or 410 status is charged like any page. A scrape answered from a stored copy within `maxAge` is free. Crawl and batch scrape charge each page when it finishes. ### Parsers Scrape with a [parser](/guides/parsers) costs the parser's price, and most parsers cost 1 credit a call. These cost more, or count what comes back: | Parser | Price | | - | - | | `zillow-search` | 2 credits per call | | `google-maps-reviews` | 1 credit per 10 reviews | | `appstore-search`, `appstore-top`, `google-play-search` | 1 credit per 10 apps | | `craigslist-search` | 1 credit per 10 listings | | `reddit-post` | 1 credit per 200 comments | | `instagram-transcript` | 1 credit plus 1 credit for every 30 seconds of audio, up to 5 minutes | | `tiktok-transcript` | 1 credit when the video has captions; otherwise 2 credits plus 1 credit for every 10 seconds of audio, up to 3 minutes | The [parser list](https://api.stophy.dev/v1/parsers) has every parser's `price`. ## What you were charged `creditsUsed` in the response, or the `x-credits-used` header, is what the call cost. Scrape puts it in `data.metadata.creditsUsed`. [Limits](/api-reference/endpoint/limits) shows your balance in credits, and [Logs](/api-reference/endpoint/logs) lists recent calls with their cost. ## Running out A call your balance can't cover answers `402` with code `insufficientCredits` and charges nothing. The `x-required-credits` and `x-available-credits` headers say what the call needs and what you have. # Anthropic Source: https://docs.stophy.dev/developer-guides/llm-sdks/anthropic Give Claude live web search with Stophy. Save one search function, define it as a tool, and let the tool runner call it when Claude asks. Give Claude live web search. Claude asks for a search, your code calls Stophy, and Claude answers from the results. ## The search tool Save this as `stophy.ts`. When Claude calls it, it returns the top 5 web results as JSON. ```ts stophy.ts theme={null} export async function stophySearch(query: string): Promise { const headers: Record = { "Content-Type": "application/json" }; if (process.env.STOPHY_API_KEY) headers.Authorization = `Bearer ${process.env.STOPHY_API_KEY}`; const response = await fetch("https://api.stophy.dev/v1/search", { method: "POST", headers, body: JSON.stringify({ query, limit: 5 }), }); const body = await response.json(); if (!body.success) throw new Error(body.error); return JSON.stringify(body.data.web); } ``` ## Give it to Claude ```bash theme={null} npm install @anthropic-ai/sdk zod ``` Set `ANTHROPIC_API_KEY` in your environment, and `STOPHY_API_KEY` to go past the free limits. `betaZodTool` defines the search as a tool. The tool runner calls it whenever Claude asks, and returns Claude's final message. ```ts theme={null} import Anthropic from "@anthropic-ai/sdk"; import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; import { z } from "zod"; import { stophySearch } from "./stophy"; const client = new Anthropic(); const webSearch = betaZodTool({ name: "web_search", description: "Search the web. Returns the top results as JSON.", inputSchema: z.object({ query: z.string().describe("What to search for") }), run: async ({ query }) => stophySearch(query), }); const message = await client.beta.messages.toolRunner({ model: "claude-sonnet-5-5", max_tokens: 16000, tools: [webSearch], messages: [{ role: "user", content: "What changed in the latest Bun release?" }], }); for (const block of message.content) { if (block.type === "text") console.log(block.text); } ``` # OpenAI Source: https://docs.stophy.dev/developer-guides/llm-sdks/openai Give an OpenAI model live web search with Stophy. Save one search function, pass it as a tool, and send the results back when the model asks. Give an OpenAI model live web search. The model asks for a search, your code calls Stophy, and the model answers from the results. ## The search tool Save this as `stophy.ts`. When the model calls it, it returns the top 5 web results as JSON. ```ts stophy.ts theme={null} export async function stophySearch(query: string): Promise { const headers: Record = { "Content-Type": "application/json" }; if (process.env.STOPHY_API_KEY) headers.Authorization = `Bearer ${process.env.STOPHY_API_KEY}`; const response = await fetch("https://api.stophy.dev/v1/search", { method: "POST", headers, body: JSON.stringify({ query, limit: 5 }), }); const body = await response.json(); if (!body.success) throw new Error(body.error); return JSON.stringify(body.data.web); } ``` ## Give it to an OpenAI model ```bash theme={null} npm install openai ``` Set `OPENAI_API_KEY` in your environment, and `STOPHY_API_KEY` to go past the free limits. Pass the search as a function tool to the Responses API. While the model keeps calling it, run the search and send the result back. ```ts theme={null} import OpenAI from "openai"; import { stophySearch } from "./stophy"; const openai = new OpenAI(); const tools: OpenAI.Responses.Tool[] = [ { type: "function", name: "web_search", description: "Search the web. Returns the top results as JSON.", parameters: { type: "object", properties: { query: { type: "string", description: "What to search for" } }, required: ["query"], additionalProperties: false, }, strict: true, }, ]; let response = await openai.responses.create({ model: "gpt-5-mini", input: "What changed in the latest Bun release?", tools, }); while (true) { const calls = response.output.filter((item) => item.type === "function_call"); if (calls.length === 0) break; const outputs: OpenAI.Responses.ResponseInputItem[] = []; for (const call of calls) { const { query } = JSON.parse(call.arguments) as { query: string }; outputs.push({ type: "function_call_output", call_id: call.call_id, output: await stophySearch(query) }); } response = await openai.responses.create({ model: "gpt-5-mini", previous_response_id: response.id, input: outputs, tools, }); } console.log(response.output_text); ``` # Vercel AI SDK Source: https://docs.stophy.dev/developer-guides/llm-sdks/vercel-ai-sdk Give any AI SDK model live web search with Stophy. Save one search function, wrap it in tool() with zod, and let the model call it in generateText. Give any AI SDK model live web search. The model asks for a search, `execute` calls Stophy, and the model answers from the results. ## The search tool Save this as `stophy.ts`. When `execute` calls it, it returns the top 5 web results as JSON. ```ts stophy.ts theme={null} export async function stophySearch(query: string): Promise { const headers: Record = { "Content-Type": "application/json" }; if (process.env.STOPHY_API_KEY) headers.Authorization = `Bearer ${process.env.STOPHY_API_KEY}`; const response = await fetch("https://api.stophy.dev/v1/search", { method: "POST", headers, body: JSON.stringify({ query, limit: 5 }), }); const body = await response.json(); if (!body.success) throw new Error(body.error); return JSON.stringify(body.data.web); } ``` ## Give it to the AI SDK ```bash theme={null} npm install ai @ai-sdk/openai zod ``` Set `OPENAI_API_KEY` in your environment, and `STOPHY_API_KEY` to go past the free limits. Wrap the search in `tool()`. `stopWhen` lets the model search, read the results and answer in up to five steps. Any AI SDK model works, so swap `openai(...)` for another provider. ```ts theme={null} import { openai } from "@ai-sdk/openai"; import { generateText, stepCountIs, tool } from "ai"; import { z } from "zod"; import { stophySearch } from "./stophy"; const { text } = await generateText({ model: openai("gpt-5-mini"), prompt: "What changed in the latest Bun release?", tools: { webSearch: tool({ description: "Search the web. Returns the top results as JSON.", inputSchema: z.object({ query: z.string().describe("What to search for") }), execute: async ({ query }) => stophySearch(query), }), }, stopWhen: stepCountIs(5), }); console.log(text); ``` # Handle errors and retries Source: https://docs.stophy.dev/guides/errors-and-retries Read the error code, retry only rate limits and outages, wait for Retry-After, and back off. A failed call costs nothing. Retry loops for TypeScript and Python. ## Decide what to do `retryAfterSeconds` in the body and the `Retry-After` header are the same number of seconds, so read either one. When neither is there, back off: wait 0.5 s, then 1 s, then 2 s. If the wait is longer than a minute, stop retrying. A `freeLimit` wait can be hours, so get a key instead. | Code | Status | Retry | Wait | Most tries | | - | - | - | - | - | | `invalidRequest`, `unsupportedMediaType`, `payloadTooLarge` | 400, 413, 415 | No | Fix the request, or read `error`. | 1 | | `apiKeyRequired`, `unauthorized` | 401 | No | Get a key at `signupUrl`, or call `signup`. | 1 | | `insufficientCredits` | 402 | No | Top up at [stophy.dev/billing](https://stophy.dev/billing). The `x-required-credits` and `x-available-credits` headers say by how much. | 1 | | `forbidden`, `siteNotRead`, `notFound`, `jobFinished` | 403, 404, 409 | No | Change the request. `siteNotRead` needs a [parser](/guides/parsers). | 1 | | `freeLimit`, `rateLimited` | 429 | Yes | `retryAfterSeconds`, else back off. | 3 | | `internalError`, `sourceUnavailable`, `sourceRefused`, `sourceTimeout` | 500, 503, 504 | Yes | `retryAfterSeconds`, else back off. | 3 | | `sourceChanged` | 502 | No | Retrying will not help yet. | 1 | After the last try, stop and log the `X-Request-ID` header. A failed call costs nothing, so a retry costs nothing extra. [Errors](/api-reference/errors) lists every code. ## A retry loop ```ts TypeScript theme={null} const RETRY = new Set(["freeLimit", "rateLimited", "internalError", "sourceUnavailable", "sourceRefused", "sourceTimeout"]); async function call(path: string, input: object, attempts = 3) { for (let attempt = 0; ; attempt++) { const response = await fetch(`https://api.stophy.dev${path}`, { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(input), signal: AbortSignal.timeout(65_000), }); const body = await response.json(); if (response.ok) return body; if (!RETRY.has(body.code) || attempt + 1 >= attempts) { throw new Error(`${body.code}: ${body.error} (${response.headers.get("x-request-id")})`); } const seconds = body.retryAfterSeconds ?? 0.5 * 2 ** attempt; await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); } } const page = await call("/v1/scrape", { url: "https://bun.com/docs/runtime/bunfig" }); ``` ```python Python theme={null} import os import time import requests RETRY = {"freeLimit", "rateLimited", "internalError", "sourceUnavailable", "sourceRefused", "sourceTimeout"} def call(path, payload, attempts=3): for attempt in range(attempts): response = requests.post( f"https://api.stophy.dev{path}", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json=payload, timeout=65, ) body = response.json() if response.ok: return body if body["code"] not in RETRY or attempt + 1 >= attempts: raise RuntimeError(f"{body['code']}: {body['error']} ({response.headers.get('x-request-id')})") time.sleep(body.get("retryAfterSeconds", 0.5 * 2**attempt)) page = call("/v1/scrape", {"url": "https://bun.com/docs/runtime/bunfig"}) ``` ## Timeouts Most calls answer within 15 seconds. A slow page, a long PDF or a transcript can take up to a minute. Set your client timeout to at least 65 seconds. Crawl, batch scrape, extract and browser tasks answer at once with an `id`, and you read the result with their status calls. # Extract with a schema Source: https://docs.stophy.dev/guides/extract-with-a-schema Send a Pydantic or zod model to extract as a JSON Schema and read the fields back from the page. Needs an API key. [Extract](/api-reference/endpoint/extract) takes the fields you want as a JSON Schema in `schema`. The output of Pydantic's `model_json_schema()` and zod's `toJSONSchema()` works as it is, including `enum`, `anyOf`, nullable types and `$ref` with `$defs`. A field the page does not state comes back `null`. The same schema works in the `json` format of [scrape](/api-reference/endpoint/scrape). The call answers with an `id`. Read the result from `GET /v1/extract/{id}`. ## Pydantic ```python theme={null} import os import time import requests from pydantic import BaseModel from typing import Literal class Plan(BaseModel): name: str price: float | None billing: Literal["monthly", "yearly"] class Pricing(BaseModel): product: str plans: list[Plan] headers = {"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"} started = requests.post( "https://api.stophy.dev/v1/extract", headers=headers, json={"urls": ["https://example.com/pricing"], "schema": Pricing.model_json_schema()}, ).json() result = requests.get(f"https://api.stophy.dev/v1/extract/{started['id']}", headers=headers).json() print(Pricing.model_validate(result["data"])) ``` ## zod ```typescript theme={null} import { z } from "zod"; const Pricing = z.object({ product: z.string(), plans: z.array( z.object({ name: z.string(), price: z.number().nullable(), billing: z.enum(["monthly", "yearly"]), }), ), }); const headers = { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "content-type": "application/json", }; const started = await fetch("https://api.stophy.dev/v1/extract", { method: "POST", headers, body: JSON.stringify({ urls: ["https://example.com/pricing"], schema: z.toJSONSchema(Pricing) }), }).then((response) => response.json()); const result = await fetch(`https://api.stophy.dev/v1/extract/${started.id}`, { headers }).then( (response) => response.json(), ); console.log(Pricing.parse(result.data)); ``` ## Limits A schema takes up to 100 top-level fields and 32 KB. Extract costs 5 credits for most pages, and a call that finds none of the fields is free. # Page through results Source: https://docs.stophy.dev/guides/paging Get the next page of a parser with the cursor or page it returns, and read a big crawl or batch scrape by following each status response's next link. Two things in Stophy come back in pages: [parsers](/guides/parsers) that read lists, and the results of a [crawl](/api-reference/endpoint/crawl) or [batch scrape](/api-reference/endpoint/batch-scrape). Paging needs an API key. ## Parsers A parser that reads a list returns `cursor` or `page` in `data.json` when there is more. Send the same request again with that value in the format's `options`. This asks for the second page of a Reddit search. The first response had `"cursor": "MjQ="`. ```bash theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.reddit.com/search/?q=web+scraping&sort=top&t=year","formats":[{"type":"json","parser":"reddit-search","options":{"cursor":"MjQ="}}]}' ``` It returned the next 25 posts and `"cursor": "NDk="` for the page after. Keep the URL and the rest of the format the same between pages. The last page has no `cursor`. A parser that takes `page` works the same way: send `"options": {"page": 2}`, then `3`, until the results are empty. Each parser's options are on its [parser page](/sources/social) and in the [parser list](https://api.stophy.dev/v1/parsers). Each page is a new call and costs the parser's price. ```ts TypeScript theme={null} const format = { type: "json", parser: "reddit-search" }; const url = "https://www.reddit.com/search/?q=web+scraping&sort=top&t=year"; const posts = []; let cursor: string | undefined; for (let page = 0; page < 3; page += 1) { const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url, formats: [cursor === undefined ? format : { ...format, options: { cursor } }] }), }); const { data } = await response.json(); posts.push(...data.json.results); cursor = data.json.cursor; if (cursor === undefined) break; } ``` ```python Python theme={null} import os import requests fmt = {"type": "json", "parser": "reddit-search"} url = "https://www.reddit.com/search/?q=web+scraping&sort=top&t=year" posts = [] cursor = None for _ in range(3): options = {"options": {"cursor": cursor}} if cursor else {} response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={"url": url, "formats": [{**fmt, **options}]}, ) data = response.json()["data"] posts.extend(data["json"]["results"]) cursor = data["json"].get("cursor") if not cursor: break ``` ## Crawl and batch scrape [Crawl](/api-reference/endpoint/crawl) and [batch scrape](/api-reference/endpoint/batch-scrape) answer at once with an `id`. Read the pages with [crawl status](/api-reference/endpoint/crawl-status) or [batch scrape status](/api-reference/endpoint/batch-scrape-status). Reading status is free, and it needs the same key. A status answer holds up to 100 finished pages or 2 MB, whichever comes first. This is separate from the `limit` you sent to crawl, which is how many pages the crawl reads in all. A crawl with `limit` 30 is usually read in one status call once it is done, and one with `limit` 250 in three. While the job runs, `status` is `scraping`. `total` is the number of pages found so far, and it grows. `completed` is how many are finished. `data` holds the finished pages. `next` appears only when more finished pages are waiting, so it never leads to an empty `data`. 1. Poll the status URL every few seconds until `status` is `completed`, `failed` or `cancelled`. 2. Follow `next` until the answer has none. Each `next` is a full URL on api.stophy.dev. Call it with the same key. ```json theme={null} { "status": "completed", "total": 250, "completed": 250, "next": "https://api.stophy.dev/v1/crawl/job_3a2Bj6qUFGZFq-y-1MWdaA?cursor=-IEUnTHVpage_100", "data": [ ... ] } { "status": "completed", "total": 250, "completed": 250, "next": "https://api.stophy.dev/v1/crawl/job_3a2Bj6qUFGZFq-y-1MWdaA?cursor=1owY_-gJpage_200", "data": [ ... ] } { "status": "completed", "total": 250, "completed": 250, "data": [ ... ] } ``` ```ts TypeScript theme={null} const headers = { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` }; const url = `https://api.stophy.dev/v1/crawl/${id}`; const over = new Set(["completed", "failed", "cancelled"]); let status = await (await fetch(url, { headers })).json(); while (!over.has(status.status)) { await new Promise((resolve) => setTimeout(resolve, 2000)); status = await (await fetch(url, { headers })).json(); } const pages = [...status.data]; let next: string | undefined = status.next; while (next !== undefined) { const more = await (await fetch(next, { headers })).json(); pages.push(...more.data); next = more.next; } ``` ```python Python theme={null} import os import time import requests headers = {"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"} url = f"https://api.stophy.dev/v1/crawl/{job_id}" status = requests.get(url, headers=headers).json() while status["status"] not in ("completed", "failed", "cancelled"): time.sleep(2) status = requests.get(url, headers=headers).json() pages = list(status["data"]) next_url = status.get("next") while next_url: more = requests.get(next_url, headers=headers).json() pages.extend(more["data"]) next_url = more.get("next") ``` Batch scrape works the same way at `https://api.stophy.dev/v1/batch/scrape/`. A crawl and its pages are kept for 24 hours. # Parsers Source: https://docs.stophy.dev/guides/parsers Read a site's own data as JSON: send its page to scrape and name one of 103 parsers, like reddit-search, youtube-transcript or google-maps. A parser reads one kind of page on one site and returns the site's own data as JSON. A Reddit search page comes back as posts, a YouTube video link as its transcript, a Google Maps search as places. There are 103 parsers. ## Call a parser Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. Parser options go in `options`. ```bash theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","formats":[{"type":"json","parser":"youtube-transcript","options":{"language":"en"}}]}' ``` > [accordion] Response > > This real response is cut. > > ```json theme={null} > { > "success": true, > "data": { > "json": { > "videoId": "dQw4w9WgXcQ", > "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", > "language": "en", > "isAutoGenerated": false, > "durationSeconds": 213, > "text": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules and so do I ♪ …" > }, > "metadata": { > "sourceURL": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", > "statusCode": 200, > "contentType": "application/json", > "scrapeId": "a506455f-08f7-4a72-abee-ddffcd984fef", > "creditsUsed": 1 > } > } > } > ``` The parser's data is in `data.json`. The URL must be the kind of page the parser reads, or the call fails with `invalidRequest`. ## Find a parser The parser pages list every parser by topic, with the page it reads, its options, what it returns, its price and a real response: > [card] [Search and the web](/sources/web) > [card] [Video](/sources/video) > [card] [Social](/sources/social) > [card] [Places and travel](/sources/places-and-travel) > [card] [Jobs](/sources/jobs) > [card] [Shopping](/sources/shopping) > [card] [Apps](/sources/apps) > [card] [Real estate](/sources/real-estate) > [card] [Ads](/sources/ads) Your code or your agent can read the same list from [`GET /v1/parsers`](/api-reference/endpoint/list-parsers). It is free and needs no key. ```bash theme={null} curl -s https://api.stophy.dev/v1/parsers \ | jq -r '.data.parsers[] | select(.name | startswith("youtube")) | "\(.name): \(.takes)"' ``` ```text theme={null} youtube-search: A YouTube search results page with the search in search_query youtube-video: A YouTube video link: watch, youtu.be, shorts or live youtube-transcript: A YouTube video link: watch, youtu.be, shorts or live youtube-comments: A YouTube video link: watch, youtu.be, shorts or live youtube-channel: A YouTube channel link: @handle, /channel/, /c/ or /user/, with an optional tab youtube-post: A YouTube community post link: /post/Ugkx... or a community page with ?lb= youtube-playlist: A YouTube playlist page with list in the link ``` Each entry has `takes` (the page it reads), an `example` URL, its `options`, the fields it `returns`, its `price`, `keyless: true` when it works without a key, and a sample `response`. Some parsers read more than one kind of page and list each one in `views`. Set `options.view` to pick one where `takes` says so. ## Price and keys Each parser has its own price in credits, most of them 1 credit a call. The parsers marked `keyless: true` work without a key, within the [free limits](/rate-limits). Paging through a parser's results needs a key. See [Page through results](/guides/paging). # Introduction Source: https://docs.stophy.dev/introduction Give your agents the live web. Search, scrape any page as markdown, crawl a site, extract fields, and read 103 sites as JSON through parsers. Stophy is one API for the live web. Your agent can: * [Search](/api-reference/endpoint/search) the web, news and images. * [Scrape](/api-reference/endpoint/scrape) any public page as markdown, HTML, links, a screenshot or JSON. * [Map](/api-reference/endpoint/map) a site's pages, [crawl](/api-reference/endpoint/crawl) a site, or [batch scrape](/api-reference/endpoint/batch-scrape) many pages. * [Extract](/api-reference/endpoint/extract) the fields you name from a page. * Read a site's own data, like a Reddit search, a YouTube transcript or Google Maps places, through one of 103 [parsers](/guides/parsers). Search, scrape, map and parse work without a key, within [free limits](/rate-limits). ## Connect your agent ```bash Claude Code theme={null} claude mcp add --transport http stophy https://api.stophy.dev/mcp ``` ```bash Codex theme={null} codex mcp add stophy --url https://api.stophy.dev/mcp ``` Your agent can call the free endpoints right away. For every endpoint, add `https://mcp.stophy.dev/mcp` instead and sign in with your browser. [MCP server](/mcp-server) covers Cursor, Claude Desktop and other clients. ## Next > [card] [Quickstart](/quickstart) > > Make a call from cURL, TypeScript or Python. > [card] [Parsers](/guides/parsers) > > Read a site's own data as JSON. > [card] [Pricing](/billing) > > Most calls cost 1 credit, and you start with 5,000 free. > [card] [API reference](/api-reference/introduction) > > Every endpoint, with its inputs, outputs and price. # MCP server Source: https://docs.stophy.dev/mcp-server Connect Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude or Grok to Stophy with one command or one URL, and sign in with your browser. ## Add Stophy to your client Each of these connects to `https://mcp.stophy.dev/mcp` and opens your browser to sign in, so your agent can use every endpoint. ```bash Claude Code theme={null} claude mcp add --transport http stophy https://mcp.stophy.dev/mcp # then run /mcp in Claude Code, choose stophy and pick Authenticate ``` ```bash Codex theme={null} codex mcp add stophy --url https://mcp.stophy.dev/mcp codex mcp login stophy ``` ```bash Gemini CLI theme={null} gemini extensions install https://github.com/stophydotdev/stophy # then run /mcp auth stophy in Gemini CLI ``` ```json Cursor (~/.cursor/mcp.json) theme={null} { "mcpServers": { "stophy": { "url": "https://mcp.stophy.dev/mcp" } } } ``` ```json Windsurf (~/.codeium/windsurf/mcp_config.json) theme={null} { "mcpServers": { "stophy": { "serverUrl": "https://mcp.stophy.dev/mcp" } } } ``` ```json OpenCode (opencode.json) theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "stophy": { "type": "remote", "url": "https://mcp.stophy.dev/mcp", "enabled": true } } } ``` VS Code connects with no key or an API key. See [No key and API key](/mcp-server/keyless). ## Add Stophy to a chat app * **Claude** on the web, desktop or mobile: open **Customize > Connectors**, click **+ Add**, then **Add custom connector**, and paste `https://mcp.stophy.dev/mcp`. See [Claude Desktop](/quickstarts/claude-desktop). * **Grok** on grok.com: open [grok.com/connectors](https://grok.com/connectors), click **New Connector**, then **Custom**, paste `https://mcp.stophy.dev/mcp` and sign in. ## Choose how to connect | | URL | Endpoints | | - | - | - | | Browser sign-in | `https://mcp.stophy.dev/mcp` | Every endpoint | | API key | `https://api.stophy.dev/mcp` with `Authorization: Bearer ` | Every endpoint | | No key | `https://api.stophy.dev/mcp` | Search, scrape, map and parse, within the [free limits](/rate-limits) | Both are server URLs for your client, not pages to open in a browser. [Browser sign-in](/mcp-server/oauth) explains what happens when you approve the app. ## What your agent sees | Tool | What it does | | - | - | | `stophy_search` | Searches the web, news and images | | `stophy_scrape` | Reads a page as markdown, HTML, links, a screenshot or JSON | | `stophy_map` | Lists the pages on a site | | `stophy_crawl` | Starts a crawl of a site in the background and returns its `id` | | `stophy_extract` | Pulls the fields you name from pages as JSON | | `stophy_search_endpoints` | Finds the endpoint for a task, with its cost. Free | | `stophy_describe_endpoint` | Shows an endpoint's inputs, an example and what it returns. Free | | `stophy_call` | Runs any endpoint by `id` with `input`, and optional `fields` and `maxTextLength` | | `stophy_signup` | Gets your agent an API key: it returns a link for you to approve, then the key once you call it with the code | Ask *"What are people saying about Bun on Reddit?"* and your agent calls `stophy_scrape` with a Reddit search page and the `reddit-search` [parser](/guides/parsers): ```json theme={null} { "url": "https://www.reddit.com/search/?q=bun+runtime", "formats": [{ "type": "json", "parser": "reddit-search" }] } ``` A crawl runs in the background. Your agent reads it with `stophy_call`, `id` `crawlStatus` and the crawl's `id`. Over MCP, endpoint ids are camelCase, like `crawlStatus` or `batchScrape`. A call costs the same as over HTTP. See [Pricing](/billing). To give each endpoint its own tool, add `toolsets` to the URL with a source name: ```text theme={null} https://api.stophy.dev/mcp?toolsets=web ``` # No key and API key Source: https://docs.stophy.dev/mcp-server/keyless Add Stophy to Claude Code, Codex, Cursor, VS Code, Windsurf or OpenCode with no key for the free endpoints, then add an API key to use every endpoint. ## No key ```bash Claude Code theme={null} claude mcp add --transport http stophy https://api.stophy.dev/mcp ``` ```bash Codex theme={null} codex mcp add stophy --url https://api.stophy.dev/mcp ``` ```bash VS Code theme={null} code --add-mcp '{"name":"stophy","type":"http","url":"https://api.stophy.dev/mcp"}' ``` ```json Cursor (~/.cursor/mcp.json) theme={null} { "mcpServers": { "stophy": { "url": "https://api.stophy.dev/mcp" } } } ``` ```json Windsurf (~/.codeium/windsurf/mcp_config.json) theme={null} { "mcpServers": { "stophy": { "serverUrl": "https://api.stophy.dev/mcp" } } } ``` ```json OpenCode (opencode.json) theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "stophy": { "type": "remote", "url": "https://api.stophy.dev/mcp", "enabled": true } } } ``` With no key your agent can search, scrape, map and parse, and read the parsers marked `keyless: true` in the [parser list](https://api.stophy.dev/v1/parsers), up to 10 calls a minute and 50 a day. Reddit search, YouTube transcripts and Google Maps search are among those parsers. ## Add an API key For every endpoint, [create a key](https://stophy.dev/signup) and send it to the same URL. Keep it in `STOPHY_API_KEY` or your client's secret settings, never in a file you commit. ```bash Claude Code theme={null} claude mcp add --transport http stophy https://api.stophy.dev/mcp --header "Authorization: Bearer $STOPHY_API_KEY" ``` ```bash Codex theme={null} codex mcp add stophy --url https://api.stophy.dev/mcp --bearer-token-env-var STOPHY_API_KEY ``` ```json VS Code (.vscode/mcp.json) theme={null} { "inputs": [ { "type": "promptString", "id": "stophy-key", "description": "Stophy API key", "password": true } ], "servers": { "stophy": { "type": "http", "url": "https://api.stophy.dev/mcp", "headers": { "Authorization": "Bearer ${input:stophy-key}" } } } } ``` ```json OpenCode (opencode.json) theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "stophy": { "type": "remote", "url": "https://api.stophy.dev/mcp", "enabled": true, "headers": { "Authorization": "Bearer {env:STOPHY_API_KEY}" } } } } ``` VS Code asks for the key the first time the server starts and stores it securely. A key that is wrong is refused. Remove the header to go back to the free endpoints. In Cursor, Windsurf and Gemini CLI, use [browser sign-in](/mcp-server) instead of a key. ## Check it Ask your agent this. ```text theme={null} Search YouTube for "rust tutorial" and summarize the top three videos. ``` If `stophy` shows no tools, restart your client. # Browser sign-in Source: https://docs.stophy.dev/mcp-server/oauth Connect Stophy to Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Claude or Grok by signing in with your browser. No API key to copy. Add `https://mcp.stophy.dev/mcp` to your client with the commands on the [MCP server](/mcp-server) page. It's a server URL for your client, not a page to open. Your client starts the sign-in. ## What happens 1. Your client opens stophy.dev in your browser. 2. You sign in or sign up. 3. Stophy shows which app is asking. Approve it only if you started the connection. 4. Your client connects. Calls come out of your balance. Signing out of stophy.dev disconnects the app. Your client asks you to sign in again next time. ## Check it Ask your agent this. ```text theme={null} Find coffee shops in Austin with a rating above 4.5 and list their websites. ``` Prefer a key? [Add an API key](/mcp-server/keyless#add-an-api-key). # Quickstart Source: https://docs.stophy.dev/quickstart Scrape a page with no key, then add a key to search, crawl and extract from cURL, TypeScript or Python. Most calls cost 1 credit, and you start with 5,000. ## Call it with no key ```bash theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com/docs/runtime/bunfig"}' ``` > [accordion] Response > > This real response is cut to a few fields. > > ```json theme={null} > { > "success": true, > "data": { > "markdown": "# bunfig.toml\n\nConfigure Bun's behavior using its configuration file bunfig.toml\n\n`bunfig.toml` is Bun's configuration…", > "metadata": { > "title": "bunfig.toml | Bun Docs", > "sourceURL": "https://bun.com/docs/runtime/bunfig", > "url": "https://bun.com/docs/runtime/bunfig", > "statusCode": 200, > "contentType": "text/html", > "cacheState": "hit", > "scrapeId": "f82a75f2-1f53-4abb-ac5a-9fdbc4314549", > "creditsUsed": 0 > } > } > } > ``` That is the page as markdown. Search, scrape, map and parse work like this with no key, up to 10 calls a minute and 50 a day. See [Rate limits](/rate-limits). ## Get a key Sign up at [stophy.dev/signup](https://stophy.dev/signup). Your account starts with 5,000 free credits, and most calls cost 1 credit. Create a key and save it as `STOPHY_API_KEY`. An agent can get a key with no human at the keyboard: [Sign up](/api-reference/endpoint/sign-up) returns a link for its person to approve. ## Call it with your key ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/search \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"nvidia earnings","sources":["web","news"],"limit":5}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "nvidia earnings", sources: ["web", "news"], limit: 5, }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/search", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "query": "nvidia earnings", "sources": ["web", "news"], "limit": 5, }, ) print(response.json()) ``` > [accordion] Response > > This real response is cut to one result per source. > > ```json theme={null} > { > "success": true, > "data": { > "news": [ > { > "title": "Stocks making the biggest moves midday: Micron, Tesla, Tripadvisor, AppLovin, Nvidia & more", > "url": "https://www.cnbc.com/2026/11/05/stocks-making-the-biggest-moves-midday-mu-tsla-trip-app-nvda.html", > "snippet": "Here are some of the companies making headlines in midday trading.", > "date": "2026-11-05T18:35:11.000Z", > "position": 1 > } > ], > "web": [ > { > "url": "https://nvidianews.nvidia.com/news/nvidia-announces-financial-results-for-second-quarter-fiscal-2027", > "title": "NVIDIA Announces Financial Results for Second Quarter Fiscal ...", > "description": "GAAP and non-GAAP earnings per diluted share were $2.46 and $2.22, respectively.\n\n“AI has reached its inflection…", > "position": 1 > } > ] > }, > "creditsUsed": 4 > } > ``` `creditsUsed` is what the call cost in credits. This search of web and news cost 4: 2 credits for each source. See [Pricing](/billing). ## Read a site as JSON To get a site's own data, send its page to scrape with a parser: ```bash theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.reddit.com/search/?q=web+scraping&sort=top&t=year","formats":[{"type":"json","parser":"reddit-search"}]}' ``` The posts come back in `data.json`. See [Parsers](/guides/parsers). ## Crawl a site Crawl reads many pages in the background. Start it, poll about every 2 seconds until it is `completed`, then read the pages. Send `scrapeOptions.formats` to read more than markdown, for example `["markdown","links"]`, and each page in `data` has every format the crawl read. Starting is free, and each page costs 1 credit. ```bash theme={null} ID=$(curl -s -X POST https://api.stophy.dev/v1/crawl \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://bun.com/docs","limit":10}' | jq -r .id) until [ "$(curl -s https://api.stophy.dev/v1/crawl/$ID -H "Authorization: Bearer $STOPHY_API_KEY" | jq -r .status)" != scraping ]; do sleep 2; done curl -s https://api.stophy.dev/v1/crawl/$ID -H "Authorization: Bearer $STOPHY_API_KEY" | jq '{status, completed, pages: [.data[].metadata.url], next}' ``` A status answer holds up to 100 finished pages. If it has `next`, call that URL for the rest. See [Page through results](/guides/paging). ## Scrape many pages Batch scrape takes a list of URLs and works the same way. Poll `https://api.stophy.dev/v1/batch/scrape/` about every 2 seconds until `status` is `completed`. Each page in `data` has the same shape as a scrape. ```bash theme={null} curl -X POST https://api.stophy.dev/v1/batch/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"urls":["https://bun.com/docs/runtime/bunfig","https://bun.com/docs/runtime/env"]}' ``` ## Next > [card] [Parsers](/guides/parsers) > > Read Reddit, YouTube, Google Maps and 100 more sites as JSON. > [card] [Crawl a site](/api-reference/endpoint/crawl) > > Read every page of a site in the background. # Claude Code Source: https://docs.stophy.dev/quickstarts/claude-code Add Stophy to Claude Code with one command. Start with no key, sign in with your browser, or use an API key to open every endpoint. Run this in your terminal. It adds Stophy to [Claude Code](https://code.claude.com) with the free endpoints. ```bash theme={null} claude mcp add --transport http stophy https://api.stophy.dev/mcp ``` Run `claude mcp get stophy` to check it. ## Sign in with your browser ```bash theme={null} claude mcp add --transport http stophy https://mcp.stophy.dev/mcp ``` Type `/mcp` in Claude Code, choose `stophy`, and pick Authenticate. This opens every endpoint. ## Use an API key ```bash theme={null} claude mcp add --transport http stophy https://api.stophy.dev/mcp --header "Authorization: Bearer $STOPHY_API_KEY" ``` Set `STOPHY_API_KEY` first. [Get a key](https://stophy.dev/signup). Your shell fills it in, and Claude Code saves it on your machine. Add `--scope user` to use Stophy in every project. ## Try it ```text theme={null} Use Stophy to find the top Reddit posts about Bun this week and summarize them. ``` If you see two `stophy` servers, run `claude mcp remove stophy` and add the one you want. # Claude Desktop Source: https://docs.stophy.dev/quickstarts/claude-desktop Add Stophy to Claude Desktop as a custom connector. Paste one URL, sign in with your browser, and every Stophy endpoint works in your chats. ## Add the connector 1. In [Claude Desktop](https://claude.ai/download), open **Customize > Connectors**. 2. Click **+ Add**, then **Add custom connector**. 3. Name it `Stophy` and paste this URL, then click **Continue**. ```text theme={null} https://mcp.stophy.dev/mcp ``` 4. Keep the sign-in settings Claude detects and click **Add**. Claude opens stophy.dev, where you sign in or sign up and approve the connection. The same connector works in Claude on the web and on mobile. On the Free plan, Claude allows one custom connector. ## Try it In a new chat, click **+**, then **Connectors**, and turn on Stophy. Then ask this. ```text theme={null} Use Stophy to find the top Reddit posts about Bun this week and summarize them. ``` If Stophy doesn't answer, check that the connector is on for this chat. If it asks you to sign in again, you signed out of stophy.dev, which disconnects the app. # Codex Source: https://docs.stophy.dev/quickstarts/codex Add Stophy to Codex with one command. Start with no key, sign in with your browser, or use an API key to open every endpoint. This one command gives [Codex](https://developers.openai.com/codex) the free Stophy endpoints. ```bash theme={null} codex mcp add stophy --url https://api.stophy.dev/mcp ``` Run `codex mcp list` to check it. ## Sign in with your browser ```bash theme={null} codex mcp add stophy --url https://mcp.stophy.dev/mcp codex mcp login stophy ``` This opens every endpoint. ## Use an API key ```bash theme={null} codex mcp add stophy --url https://api.stophy.dev/mcp --bearer-token-env-var STOPHY_API_KEY ``` Set `STOPHY_API_KEY` first. [Get a key](https://stophy.dev/signup). Codex reads it each time it starts, so it is never saved to `~/.codex/config.toml`. ## Try it ```text theme={null} Use Stophy to get the transcript of https://www.youtube.com/watch?v=dQw4w9WgXcQ and summarize it. ``` # Cursor Source: https://docs.stophy.dev/quickstarts/cursor Add Stophy to Cursor in one config file. Start with no key, sign in with your browser, or use an API key to open every endpoint. Add Stophy to [Cursor](https://cursor.com). Put this in `~/.cursor/mcp.json`. ```json theme={null} { "mcpServers": { "stophy": { "url": "https://api.stophy.dev/mcp" } } } ``` Restart Cursor, and its agent can call the free endpoints. ## Sign in with your browser Use this URL instead. Cursor opens your browser to sign in, and every endpoint opens. ```json theme={null} { "mcpServers": { "stophy": { "url": "https://mcp.stophy.dev/mcp" } } } ``` ## Use an API key [Get a key](https://stophy.dev/signup), then add a header. Keep the file private, since it holds your key. ```json theme={null} { "mcpServers": { "stophy": { "url": "https://api.stophy.dev/mcp", "headers": { "Authorization": "Bearer YOUR_STOPHY_API_KEY" } } } } ``` ## Try it Open the MCP section of Cursor Settings and check that `stophy` is on. Then ask the agent this. ```text theme={null} Use Stophy to find coffee shops near Austin, TX with their ratings. ``` # Rate limits Source: https://docs.stophy.dev/rate-limits Stophy allows 600 requests a minute per account. Without a key, search, scrape, map and parse allow 10 calls a minute and 50 a day per IP address. ## Limits | | Limit | | - | - | | With a key | 600 requests a minute per account | | Without a key | 10 requests a minute and 50 a day per IP address | Without a key you can call [search](/api-reference/endpoint/search), [scrape](/api-reference/endpoint/scrape), [map](/api-reference/endpoint/map) and [parse](/api-reference/endpoint/parse), over HTTP and [MCP](/mcp-server/keyless). They are the endpoints marked keyless on their reference pages. Scrape with a [parser](/guides/parsers) works without a key when the parser is marked `keyless: true` in the [parser list](https://api.stophy.dev/v1/parsers). Paging, crawl, batch scrape, extract and browser tasks need a key. [Sign up](https://stophy.dev/signup) to lift the limits. Responses include the `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. Without a key they count the day's calls. ## When you go over | Code | Status | What to do | | - | - | - | | `rateLimited` | `429` | Wait the number of seconds in `retryAfterSeconds`, which is also the `Retry-After` header, then retry. | | `freeLimit` | `429` | Get a key at `signupUrl`, or wait for `retryAfterSeconds`. | [Errors and retries](/guides/errors-and-retries) has a retry loop. # Resources for agents Source: https://docs.stophy.dev/resources Give your AI agent the right Stophy resource. agents.md sets up a project, llms.txt finds endpoints, and the OpenAPI document gives typed tools. | Resource | Use it to | | - | - | | [agents.md](https://stophy.dev/agents.md) | Add Stophy to a project, with a client, a key and a first call. | | [llms.txt](https://stophy.dev/llms.txt) | Find the right endpoint for a task. | | [Docs index](https://docs.stophy.dev/llms.txt) | Find a page in these docs. | | [OpenAPI document](https://api.stophy.dev/openapi.json) | Generate a typed client, or give a model every endpoint as a tool. | | [MCP discovery](https://stophy.dev/.well-known/mcp.json) | Read the MCP server's tools and sign-in. | | [Parser list](https://api.stophy.dev/v1/parsers) | List every parser with the page it reads, what it returns and its price. | # CLI Source: https://docs.stophy.dev/sdks/cli Install the Stophy CLI, search and scrape with no login, then log in to read sites through parsers, crawl, extract and set up your agents. Give your agents the live web from your terminal. Try it with no key: ```bash theme={null} curl -fsSL https://stophy.dev/install | bash stophy search "bun runtime" ``` Results print as rows, or as JSON with `--json`. ## Install The installer puts the binary in `~/.local/bin`. On Windows, use PowerShell: ```powershell theme={null} irm https://stophy.dev/install.ps1 | iex ``` With Node.js 20 or later, `npm install -g @stophy/cli` works too. ## Set up your agent ```bash theme={null} stophy init --all ``` `init` logs you in with your browser, installs the Stophy skills with `npx -y skills add stophydotdev/stophy`, and adds the MCP server. With Claude Code on your PATH it runs `claude mcp add`. For any other agent it prints the command or snippet to use, and leaves your config files alone. | Option | What it does | | - | - | | `--all` | Run every step without asking | | `--agent ` | Set up one agent, such as `claude-code` or `codex` | | `--skip-auth` | Do not log in | | `--skip-skills` | Do not install the skills | | `--skip-mcp` | Do not add the MCP server | ## Log in ```bash theme={null} stophy login --browser ``` The CLI prints a code and opens stophy.dev. Check that the page shows the same code, then click **Approve**. On a server with no browser, open the printed link on any other device. To use an API key from the [dashboard](https://stophy.dev/dashboard) instead, run this and paste the key when it asks, so it stays out of your shell history. In CI, set `STOPHY_API_KEY` from your secret store. ```bash theme={null} stophy login --api-key ``` Each computer gets its own key, and logging in again replaces it. `stophy logout` logs out and revokes the key. Without a login you can run the commands `stophy endpoints` marks `free`, within a small free allowance. ## Get data ```bash theme={null} stophy search "bun runtime" --limit 5 stophy scrape https://bun.com/docs stophy map https://bun.com --limit 50 stophy crawl https://bun.com/docs --limit 20 stophy crawl status stophy extract --urls https://bun.com --prompt "the latest version" stophy extract status ``` `stophy --help` lists every option. * Give a list as `--urls a,b` or `--urls a --urls b`. * Turn a yes-or-no option on with `--flag` and off with `--no-flag`. * Options that take JSON, like `--formats '["markdown","links"]'`, take it as one quoted argument. * A value the command doesn't take stops the CLI before it calls Stophy, and it prints the values that work. `crawl`, `batch scrape` and `extract` answer with an id. Read the result with `status ` and stop a running job with `cancel `. A status answer holds up to 100 finished pages. Wait until the status is `completed`. When it has a `next` link, run it again with `--cursor` and the cursor from that link. ## Read a site with a parser A parser returns a site's own data as JSON: posts, videos, places, products, jobs, listings and more. `stophy parsers [word]` lists them, with the kind of page each one takes: ```bash theme={null} stophy parsers reddit stophy scrape "https://www.reddit.com/r/rust/" --parser reddit-subreddit stophy scrape https://youtu.be/M4TufsFlv_o --parser youtube-transcript ``` If the output ends with a `cursor`, get the next page with `--parserOptions '{"cursor":""}'`. `--json` prints the data as JSON and the cost to stderr. `--raw` prints the full response. `-o ` writes the output to a file. A failed call ends with `Request id: `, which support will ask for. ## Commands | Command | What it does | | - | - | | `stophy init` | Set up Stophy in your coding agents | | `stophy login` | Log in with your browser or an API key | | `stophy logout` | Log out and revoke this computer's key | | `stophy ` | Get data, for example `stophy search` | | `stophy parsers [word]` | List the parsers `scrape --parser` takes | | `stophy endpoints [word]` | List every command and its price | | `stophy status` | Show your login, balance and CLI version | | `stophy usage` | Show your balance and all-time usage | | `stophy logs --days 7` | Show your recent requests | | `stophy doctor` | Check your install, login and connection | | `stophy version` | Show the CLI version | The CLI tells you when a newer version is out. Set `STOPHY_NO_UPDATE_CHECK=1` to turn that off. # Overview Source: https://docs.stophy.dev/sdks/overview Pick a Stophy client. Use the TypeScript or Python SDK in your code, or the CLI in your terminal and for AI agents that run shell commands. Call Stophy from TypeScript, Python or your terminal. All three call the same [API](/api-reference/introduction) and read `STOPHY_API_KEY` from your environment. ## Install ```bash TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null} npm install stophy ``` ```bash Python icon="python" theme={null} pip install stophy ``` ```bash CLI icon="square-terminal" theme={null} curl -fsSL https://stophy.dev/install | bash ``` ## Pick one > [card] [TypeScript](/sdks/typescript) > > For Node.js, Bun, Deno and the browser. Typed inputs and results. > [card] [Python](/sdks/python) > > For Python apps and scripts. Sync and async clients. > [card] [CLI](/sdks/cli) > > For your terminal, your scripts, and agents that run shell commands. Get a key in the [Quickstart](/quickstart). # Python SDK Source: https://docs.stophy.dev/sdks/python Install the Stophy Python SDK, scrape and search with no key, then add a key to read sites through parsers, crawl, extract and run async. Give your agents the live web from Python. Every method and result is typed. ## Install ```bash theme={null} pip install stophy ``` ## Try it without a key ```python theme={null} from stophy import Stophy stophy = Stophy() page = stophy.scrape(url="https://example.com", formats=["markdown"]) print(page["data"]["markdown"]) results = stophy.search(query="bun runtime", limit=3) print(results["data"]["web"]) ``` `scrape`, `search`, `map` and `parse` work without a key, within a small free allowance. Every other method raises a `StophyError` with the code `apiKeyRequired`. ## Use an API key Get a key at [stophy.dev/signup](https://stophy.dev/signup). Set it as `STOPHY_API_KEY`, or pass it in: ```python theme={null} stophy = Stophy(api_key="st_...") ``` Each method sends one call to the [Stophy API](/api-reference/introduction) and returns its JSON as a dict. `scrape` returns `success` and `data`, and `map` returns `success` and `links`. Arguments are keyword-only and snake\_case. For async code, use `AsyncStophy`. It has the same methods, and you `await` each call. ## Read a site with a parser A parser reads a site's page and returns its data as JSON: Reddit posts, Google Maps places, Amazon products, YouTube videos and more. Send the parser's name and the page URL: ```python theme={null} places = stophy.parsed("google-maps", "https://www.google.com/maps/search/dentists+in+Ljubljana") print(places["data"]["json"]) ``` `parsed` calls `scrape` with the format `{"type": "json", "parser": ...}`. The parser name is typed as `ParserName`. `stophy.parsers()` returns each parser with the page it reads and what it returns. Extra keyword arguments are the parser's options, such as the next page: ```python theme={null} next_page = stophy.parsed( "google-maps", "https://www.google.com/maps/search/dentists+in+Ljubljana", page=2 ) ``` Paging needs an API key. ## Crawl a site `crawl` answers at once with an id. Ask `crawl.status` for the pages: ```python theme={null} job = stophy.crawl(url="https://bun.com/docs", limit=20) status = stophy.crawl.status(id=job["id"]) print(status["status"], status["completed"], status["total"], status.get("data")) ``` `status` is `scraping` until the crawl is `completed`. A status answer holds up to 100 finished pages. Wait until the status is `completed`. When the answer has a `next` link, send the `cursor` value from that link with the same id to get the rest. `stophy.crawl.cancel(id=...)` stops the crawl and keeps the pages already read. A crawl and its pages are kept for 24 hours. `stophy.batch.scrape(urls=[...])` takes a list of URLs and works the same way, with `batch.scrape.status` and `batch.scrape.cancel`. ## Extract fields from pages ```python theme={null} job = stophy.extract(urls=["https://example.com"], prompt="What is this page for?") result = stophy.extract.result(id=job["id"]) print(result["data"], result["confidence"]) ``` `extract.result` raises a `StophyError` with the code `notFound` until the result is ready. Results are kept for 24 hours. ## Handle errors ```python theme={null} from stophy import StophyError try: stophy.scrape(url="not a url") except StophyError as error: print(error.code, str(error), error.retryable) ``` `StophyError` has `code`, `retryable`, `retry_after_seconds`, `status`, and `request_id`. The message is `str(error)`. It says what went wrong and what to do next. The SDK retries network errors and the HTTP statuses 429, 500, 502, 503, and 504, and it waits as long as the API asks. If the API asks for a wait longer than 60 seconds, the SDK raises right away with `retry_after_seconds` set. ## Options | Option | Default | What it does | | - | - | - | | `api_key` | `STOPHY_API_KEY` | Your API key | | `base_url` | `STOPHY_BASE_URL`, or the Stophy API | The server to call | | `max_retries` | `2` | Retries per request. `0` turns retries off. | | `timeout` | `70.0` | Time limit in seconds for each attempt | ## Check your account ```python theme={null} limits = stophy.limits() usage = stophy.usage() logs = stophy.logs(days=7) ``` `limits` returns your balance and rate limit. `usage` returns your all-time usage. `logs` returns your recent calls. All three need an API key. # TypeScript SDK Source: https://docs.stophy.dev/sdks/typescript Install the Stophy TypeScript SDK, scrape and search with no key, then add a key to read sites through parsers, crawl, extract and handle errors. Give your agents the live web from TypeScript. Every method and result is typed. ## Install ```bash theme={null} npm install stophy ``` ## Try it without a key ```ts theme={null} import { Stophy } from "stophy"; const stophy = new Stophy(); const page = await stophy.scrape({ url: "https://example.com", formats: ["markdown"] }); console.log(page.data.markdown); const results = await stophy.search({ query: "bun runtime", limit: 3 }); console.log(results.data?.web); ``` `scrape`, `search`, `map` and `parse` work without a key, within a small free allowance. Every other method throws a `StophyError` with the code `apiKeyRequired`. ## Use an API key Get a key at [stophy.dev/signup](https://stophy.dev/signup). Set it as `STOPHY_API_KEY`, or pass it in: ```ts theme={null} const stophy = new Stophy({ apiKey: "st_..." }); ``` `new Stophy("st_...")` works too. Each method sends one call to the [Stophy API](/api-reference/introduction) and returns its JSON as is. `scrape` returns `{ success, data }`, and `map` returns `{ success, links }`. ## Read a site with a parser A parser reads a site's page and returns its data as JSON: Reddit posts, Google Maps places, Amazon products, YouTube videos and more. Send the page URL and the parser's name: ```ts theme={null} const places = await stophy.parsed( "google-maps", "https://www.google.com/maps/search/dentists+in+Ljubljana", ); console.log(places.data.json); ``` `parsed` calls `scrape` with the format `{ type: "json", parser }`. The parser name is typed, so your editor lists every parser. `await stophy.parsers()` returns each parser with the page it reads and what it returns. The third argument sends the parser's options, such as the next page: ```ts theme={null} const next = await stophy.parsed( "google-maps", "https://www.google.com/maps/search/dentists+in+Ljubljana", { page: 2 }, ); ``` Paging needs an API key. ## Crawl a site `crawl` answers at once with an id. Ask `crawl.status` for the pages: ```ts theme={null} const job = await stophy.crawl({ url: "https://bun.com/docs", limit: 20 }); if (job.id) { const status = await stophy.crawl.status({ id: job.id }); console.log(status.status, status.completed, status.total, status.data); } ``` `status` is `scraping` until the crawl is `completed`. A status answer holds up to 100 finished pages. Wait until the status is `completed`. When the answer has a `next` link, send the `cursor` value from that link with the same id to get the rest. `crawl.cancel({ id })` stops the crawl and keeps the pages already read. A crawl and its pages are kept for 24 hours. `batch.scrape` takes a list of URLs and works the same way, with `batch.scrape.status` and `batch.scrape.cancel`. ## Extract fields from pages ```ts theme={null} const job = await stophy.extract({ urls: ["https://example.com"], prompt: "What is this page for?", }); if (job.id) { const result = await stophy.extract.result({ id: job.id }); console.log(result.data, result.confidence); } ``` `extract.result` throws a `StophyError` with the code `notFound` until the result is ready. Results are kept for 24 hours. ## Handle errors ```ts theme={null} import { StophyError } from "stophy"; try { await stophy.scrape({ url: "not a url" }); } catch (error) { if (error instanceof StophyError) { console.log(error.code, error.message, error.retryable); } } ``` `StophyError` has `code`, `message`, `retryable`, `retryAfterSeconds`, `status`, and `requestId`. The message says what went wrong and what to do next. The SDK retries network errors and the HTTP statuses 429, 500, 502, 503, and 504, and it waits as long as the API asks. If the API asks for a wait longer than 60 seconds, the SDK throws right away with `retryAfterSeconds` set. ## Options | Option | Default | What it does | | - | - | - | | `apiKey` | `STOPHY_API_KEY` | Your API key | | `baseUrl` | `STOPHY_BASE_URL`, or the Stophy API | The server to call | | `maxRetries` | `2` | Retries per request. `0` turns retries off. | | `timeoutMs` | `70000` | Time limit for each attempt. A timed-out attempt is not retried. | Each method also takes `signal` to cancel the request. ## Check your account ```ts theme={null} const limits = await stophy.limits(); const usage = await stophy.usage(); const logs = await stophy.logs({ days: 7 }); ``` `limits` returns your balance and rate limit. `usage` returns your all-time usage. `logs` returns your recent calls. All three need an API key. # Ads Source: https://docs.stophy.dev/sources/ads Search the public ad libraries of Meta, Google, TikTok and LinkedIn as JSON. Get each ad's creative and copy, and find the advertisers behind them. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_exact_phrase","formats":[{"type":"json","parser":"meta-ads"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_exact_phrase", formats: [{ type: "json", parser: "meta-ads" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike&search_type=keyword_exact_phrase", "formats": [{"type": "json", "parser": "meta-ads"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "meta-ads", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`meta-ads`](#meta-ads) | A Meta Ad Library search page with a q keyword, a page view with a view\_all\_page\_id, or an ad page with an id. | 1 credit per call. | | [`google-ads`](#google-ads) | A Google Ads Transparency Center advertiser page, ad page or search page with a domain. | 1 credit per call. | | [`tiktok-ads`](#tiktok-ads) | A TikTok Ad Library search page with an adv\_name keyword or advertiser, or an ad page. | 1 credit per call. | | [`linkedin-ads`](#linkedin-ads) | A LinkedIn Ad Library search page with a keyword or accountOwner, or an ad page or lnkd.in share link. | 1 credit per call. | ## meta-ads A Meta Ad Library search page with a q keyword, a page view with a view\_all\_page\_id, or an ad page with an id. * **Example page:** [https://www.facebook.com/ads/library/?active\_status=active\&ad\_type=all\&country=US\&q=nike\&search\_type=keyword\_exact\_phrase](https://www.facebook.com/ads/library/?active_status=active\&ad_type=all\&country=US\&q=nike\&search_type=keyword_exact_phrase) * **Returns:** `adId`, `adUrl`, `pageId`, `pageName`, `pageUrl`, `pageAvatarUrl`. * **Options:** `mediaType` (The Ad Library's own Media type filter: image, video, or text (no image or video)), `platforms` (The Ad Library's own Platform filter: only ads shown on at least one of these platforms), `language` (The Ad Library's own Language filter: a two-letter code like en. Only ads written in this language), `shownFrom` (The Ad Library's own Impressions by date: ads shown on or after this day), `shownTo` (The Ad Library's own Impressions by date: ads shown on or before this day), `cursor` (The cursor from the previous response. Send it as is), `advertiser` (The Facebook page: its numeric id, its username, its exact name as the Ad Library lists it, or its URL), `country` (ISO 3166-1 alpha-2 country code, or all. Any case is accepted), `status`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "adId": "1550534860016399", > "adUrl": "https://www.facebook.com/ads/library/?id=1550534860016399", > "pageId": "115939511520844", > "pageName": "Perfect themes", > "pageUrl": "https://facebook.com/100093512920259", > "pageAvatarUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/701421303_1593266515068546_6584706353812290058_n.jpg?stp=dst-jpg_s60…", > "pageCategories": [ > "Topic" > ], > "pageLikes": 18581, > "isActive": true, > "firstShownAt": "2026-05-19T07:00:00.000Z", > "lastShownAt": null, > "platforms": [ > "facebook", > "instagram", > "audienceNetwork" > ], > "format": "image", > "text": "🔥🍭Themepack is a FREE and personalized APP😍 various styles of Theme💎 、Weather💖、Photo😊、Clock、Calendar to pick any…", > "linkUrl": "http://play.google.com/store/apps/details?id=com.iconchanger.widget.theme.shortcut", > "linkTitle": "𝕊𝕦𝕡𝕖𝕣 𝕙𝕠𝕥 𝕨𝕚𝕕𝕘𝕖𝕥𝕤 𝕒𝕡𝕡 !", > "linkDescription": null, > "ctaText": "Install now", > "imageUrls": [ > "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/700927950_933331229664450_6487763311056032772_n.jpg?_nc_cat=111&ccb=…" > ], > "videoUrls": [], > "cards": [], > "versions": null, > "categories": [], > "paidBy": null, > "spendMin": null, > "spendMax": null, > "spendCurrency": null, > "impressionsMin": null, > "impressionsMax": null, > "reachMin": null, > "reachMax": null, > "countries": [] > } > ], > "cursor": "AQHTFYpc21jgjbhLWsCOd9JSuy7msUL1luJh8uiG-cX_v-3pw-d_l39pX5QljfX7STmR" > } > ``` ## google-ads A Google Ads Transparency Center advertiser page, ad page or search page with a domain. Set options.view to advertisers on a search page to look up advertisers by the domain's name. * **Example page:** [https://adstransparency.google.com/?region=US\&domain=nike.com](https://adstransparency.google.com/?region=US\&domain=nike.com) * **Returns:** `adId`, `adUrl`, `advertiserId`, `advertiserName`, `advertiserUrl`, `domain`. * **Options:** `query` (A domain like nike.com. Google's library finds ads by domain or advertiser, not by keyword), `advertiser`, `mediaType`, `platform` (Google's own Platform filter: where the ad was shown. Google leaves out ads shown before 4 September 2023 when it is set), `shownFrom` (Google's own Date range: ads shown on or after this day), `shownTo` (Google's own Date range: ads shown on or before this day), `cursor` (The cursor from the previous response. Send it as is), `advertiserId` (Advertiser id like AR18378488041124659201. Send it with adId; adUrl already has it), `limit` (How many advertisers to ask Google for, 1 to 100. Google ranks the list for the count you ask, so a larger limit is not the same list with more rows added, and there are no further pages. Fewer come back when Google has fewer matches). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "adId": "CR00802554745662210049", > "adUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR00802554745662210049", > "advertiserId": "AR16735076323512287233", > "advertiserName": "Nike, Inc.", > "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233", > "domain": "nike.com", > "format": "video", > "firstShownAt": "2026-11-03T18:57:15.000Z", > "lastShownAt": "2026-11-04T21:31:04.000Z", > "daysShown": 2, > "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?client=ads-integrity-transparency&obfuscatedCus…", > "imageUrl": null > } > ], > "totalMin": 8000, > "totalMax": 9000, > "cursor": "CgoAP7zmghyLjfUzEhCWvRtPpsg95u2/n40AAAAAGgn8+GWT+NWZIHk=" > } > ``` ## tiktok-ads A TikTok Ad Library search page with an adv\_name keyword or advertiser, or an ad page. * **Example page:** [https://library.tiktok.com/ads?region=DE\&adv\_name=adidas\&query\_type=1](https://library.tiktok.com/ads?region=DE\&adv_name=adidas\&query_type=1) * **Returns:** `adId`, `adUrl`, `advertiserName`, `headline`, `firstShownAt`, `lastShownAt`. * **Options:** `advertiser` (An advertiser name. TikTok matches the name exactly, so use it as tiktok.ads.ad gives it, like Nike, Inc. When no listed advertiser has exactly this name, the closest listed name is used. Send this or query, not both), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "adId": "1871324448424097", > "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1871324448424097", > "advertiserName": "adidas AG", > "headline": "adidas Hyperboost Euphoria", > "firstShownAt": "2026-07-30T00:00:00.000Z", > "lastShownAt": "2026-08-19T00:00:00.000Z", > "reachMin": 1000000, > "reachMax": 10000000, > "videoUrl": "https://library.tiktok.com/api/v1/cdn/1793833904/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS9iZGQ3MjhjMGE4ZGM1ODQ3YzI4YWM2…", > "thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o45ljvYzEkiDA0dAUAy8mEiUBVCYs3aAhIaos~tplv-tiktokx-origin…", > "imageUrls": [ > "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o45ljvYzEkiDA0dAUAy8mEiUBVCYs3aAhIaos~tplv-tiktokx-origin…" > ] > } > ], > "total": null, > "cursor": "eyJsYXN0X3NvcnQiOlszMC41MzQyNTIsMTc4NzA5NzYwMDAwMF0sIm5leHRfY3Vyc29yIjoxMn0=~ifbul0fcf5.ifeb8tduky.ifeb8tdulu.ifbu48choh.ifeb8tdsyq.ifjx2ki5k2.ifbtkmpele.ifk..." > } > ``` ## linkedin-ads A LinkedIn Ad Library search page with a keyword or accountOwner, or an ad page or lnkd.in share link. * **Example page:** [https://www.linkedin.com/ad-library/search?keyword=software\&countries=DE](https://www.linkedin.com/ad-library/search?keyword=software\&countries=DE) * **Returns:** `adId`, `adUrl`, `creativeType`, `format`, `advertiserName`, `advertiserUrl`. * **Options:** `advertiser`, `within` (Only ads shown in the last 30 days or the last year), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "adId": "1624678994", > "adUrl": "https://www.linkedin.com/ad-library/detail/1624678994", > "creativeType": "SPONSORED_STATUS_UPDATE", > "format": "Single Image Ad", > "advertiserName": "Torii", > "advertiserUrl": null, > "advertiserAvatarUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQGF3JEvj2zgcA/company-logo_100_100/B4EZ9IPSWCJYAI-/0/1783623394930/toriihq_l…", > "postedBy": null, > "text": "Torii shows you every SaaS and AI app in the estate, who has access to each one, and what it actually costs. Most…", > "headline": "You cannot optimize software you cannot see.", > "imageUrls": [ > "https://media.licdn.com/dms/image/v2/D4E10AQG2Y8yC_MDg-Q/image-shrink_1280/B4EaGeSmFVIgAg-/0/1793657037813/torii-discov…" > ] > } > ], > "total": 148790, > "cursor": "1624832654-1793655819560" > } > ``` # Apps Source: https://docs.stophy.dev/sources/apps Search the App Store and Google Play, and get any app's details and reviews as JSON. The App Store top charts come back the same way. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://apps.apple.com/us/iphone/search?term=notes","formats":[{"type":"json","parser":"appstore-search"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://apps.apple.com/us/iphone/search?term=notes", formats: [{ type: "json", parser: "appstore-search" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://apps.apple.com/us/iphone/search?term=notes", "formats": [{"type": "json", "parser": "appstore-search"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "appstore-search", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`appstore-search`](#appstore-search) | An App Store search page, like apps.apple.com/us/iphone/search?term=notes. | 1 credit per 10 apps. | | [`appstore-app`](#appstore-app) | An App Store app page, like apps.apple.com/us/app/notes/id1110145109. | 1 credit per call. | | [`appstore-reviews`](#appstore-reviews) | An App Store app page, like apps.apple.com/us/app/notes/id1110145109. | 1 credit per call. | | [`appstore-top`](#appstore-top) | An App Store top charts page, like apps.apple.com/us/iphone/charts. | 1 credit per 10 apps. | | [`google-play-search`](#google-play-search) | A Google Play apps search page with the search in q. | 1 credit per 10 apps. | | [`google-play-app`](#google-play-app) | A Google Play app page. | 1 credit per call. | | [`google-play-reviews`](#google-play-reviews) | A Google Play app page. | 1 credit per call. | ## appstore-search An App Store search page, like apps.apple.com/us/iphone/search?term=notes. * **Example page:** [https://apps.apple.com/us/iphone/search?term=notes](https://apps.apple.com/us/iphone/search?term=notes) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `limit` (Return at most this many apps. You pay 1 credit per 10 returned). * **Price:** 1 credit per 10 apps. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "1110145109", > "url": "https://apps.apple.com/us/app/notes/id1110145109", > "title": "Notes", > "brand": "Apple", > "description": "Notes is the best place to jot down quick thoughts or to save longer notes filled with checklists, images, web links,…", > "price": { > "amount": 0, > "currency": "USD" > }, > "originalPrice": null, > "rating": 4.83929, > "reviewCount": 664487, > "availability": null, > "images": [ > "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/e8/53/65/e853659a-0888-7264-743e-0e3875d1505f/notesCalistoga-0-0-…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/f8/33/45/f833452a-b99e-b378-e885-e0e7d55a4913/01_shared-not…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/7a/ca/dd/7acadddb-f939-11d1-a1b5-eb43e12d0721/02_pdf.png/32…" > ], > "categories": [ > "Productivity" > ], > "seller": { > "id": "284417353", > "name": "Apple", > "handle": null, > "url": "https://apps.apple.com/us/developer/apple/id284417353", > "avatarUrl": null > }, > "bundleId": "com.apple.mobilenotes", > "sellerName": "Apple Inc.", > "website": null, > "priceText": "Free", > "primaryGenreId": "6007", > "primaryGenre": "Productivity", > "contentRating": "4+", > "releaseNotes": "Bug Fixes and Feature Enhancements", > "version": "2.12", > "releasedAt": "2016-05-23T21:11:44.000Z", > "updatedAt": "2026-10-26T23:35:51.000Z", > "minimumOsVersion": "15.0", > "sizeBytes": 6054912, > "languages": [ > "AR", > "CA", > "HR" > ], > "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/e8/53/65/e853659a-0888-7264-743e-0e3875d1505f/notesCalistoga-0-0-…", > "ipadScreenshotUrls": [ > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/0f/74/d2/0f74d203-5dee-a7a2-6379-06e65f6f56da/01_sidebar.pn…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/cc/94/0a/cc940a11-8f60-4c3f-8366-7ef0a948fd8f/02_handwritin…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/25/ce/f4/25cef42f-247b-f72c-09e4-ba504a54ea99/03_tags.png/3…" > ] > } > ], > "cursor": null, > "page": null, > "total": null > } > ``` ## appstore-app An App Store app page, like apps.apple.com/us/app/notes/id1110145109. * **Example page:** [https://apps.apple.com/us/app/notes/id1110145109](https://apps.apple.com/us/app/notes/id1110145109) * **Returns:** One product: `id`, `url`, `title`, `brand`, `description`, `price`, `originalPrice`, `rating`, `reviewCount`, `availability`, `images`, `categories`, `seller`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "1110145109", > "url": "https://apps.apple.com/us/app/notes/id1110145109", > "title": "Notes", > "brand": "Apple", > "description": "Notes is the best place to jot down quick thoughts or to save longer notes filled with checklists, images, web links,…", > "price": { > "amount": 0, > "currency": "USD" > }, > "originalPrice": null, > "rating": 4.83929, > "reviewCount": 664487, > "availability": null, > "images": [ > "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/e8/53/65/e853659a-0888-7264-743e-0e3875d1505f/notesCalistoga-0-0-…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/f8/33/45/f833452a-b99e-b378-e885-e0e7d55a4913/01_shared-not…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/7a/ca/dd/7acadddb-f939-11d1-a1b5-eb43e12d0721/02_pdf.png/32…" > ], > "categories": [ > "Productivity" > ], > "seller": { > "id": "284417353", > "name": "Apple", > "handle": null, > "url": "https://apps.apple.com/us/developer/apple/id284417353", > "avatarUrl": null > }, > "bundleId": "com.apple.mobilenotes", > "sellerName": "Apple Inc.", > "website": null, > "priceText": "Free", > "primaryGenreId": "6007", > "primaryGenre": "Productivity", > "contentRating": "4+", > "releaseNotes": "Bug Fixes and Feature Enhancements", > "version": "2.12", > "releasedAt": "2016-05-23T21:11:44.000Z", > "updatedAt": "2026-10-26T23:35:51.000Z", > "minimumOsVersion": "15.0", > "sizeBytes": 6054912, > "languages": [ > "AR", > "CA", > "HR" > ], > "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/e8/53/65/e853659a-0888-7264-743e-0e3875d1505f/notesCalistoga-0-0-…", > "ipadScreenshotUrls": [ > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/0f/74/d2/0f74d203-5dee-a7a2-6379-06e65f6f56da/01_sidebar.pn…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/cc/94/0a/cc940a11-8f60-4c3f-8366-7ef0a948fd8f/02_handwritin…", > "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/25/ce/f4/25cef42f-247b-f72c-09e4-ba504a54ea99/03_tags.png/3…" > ], > "subtitle": "Take note of almost anything", > "hasInAppPurchases": false, > "ratingsOne": 10729, > "ratingsTwo": 3931, > "ratingsThree": 9247, > "ratingsFour": 33586, > "ratingsFive": 606994, > "chartName": null, > "chartGenre": null, > "chartPosition": null > } > ``` ## appstore-reviews An App Store app page, like apps.apple.com/us/app/notes/id1110145109. * **Example page:** [https://apps.apple.com/us/app/notes/id1110145109](https://apps.apple.com/us/app/notes/id1110145109) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `sort`, `page` (Page number, starting at 1). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "14742302874", > "url": null, > "author": { > "id": null, > "name": "blasssiyy", > "handle": null, > "url": null, > "avatarUrl": null > }, > "rating": 5, > "title": "Great for note taking", > "text": "Amazing", > "publishedAt": "2026-11-02T16:11:53.000Z", > "likes": null, > "response": null, > "subject": null, > "isEdited": false > } > ], > "cursor": null, > "page": 1, > "total": null > } > ``` ## appstore-top An App Store top charts page, like apps.apple.com/us/iphone/charts. * **Example page:** [https://apps.apple.com/us/iphone/charts/6002?chart=top-paid](https://apps.apple.com/us/iphone/charts/6002?chart=top-paid) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `limit` (Return at most this many apps. You pay 1 credit per 10 returned). * **Price:** 1 credit per 10 apps. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "932747118", > "url": "https://apps.apple.com/us/app/shadowrocket/id932747118", > "title": "Shadowrocket", > "brand": "Shadow Launch Technology Limited", > "description": "Rule based proxy utility client for iPhone/iPad.\n\n- Capture all HTTP/HTTPS/TCP traffic from any applications on your…", > "price": { > "amount": 2.99, > "currency": "USD" > }, > "originalPrice": null, > "rating": null, > "reviewCount": null, > "availability": null, > "images": [ > "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/4f/4c/02/4f4c0272-2fe6-777f-be0e-f4fe43c30ce4/AppIcon-0-0-1x_U007…" > ], > "categories": [ > "Utilities" > ], > "seller": { > "id": "687237009", > "name": "Shadow Launch Technology Limited", > "handle": null, > "url": "https://apps.apple.com/us/developer/shadow-launch-technology-limited/id687237009", > "avatarUrl": null > }, > "rank": 1, > "bundleId": "com.liguangming.Shadowrocket", > "genreId": "6002", > "releasedAt": "2015-04-14T02:09:18.000Z", > "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/4f/4c/02/4f4c0272-2fe6-777f-be0e-f4fe43c30ce4/AppIcon-0-0-1x_U007…" > } > ], > "cursor": null, > "page": null, > "total": null > } > ``` ## google-play-search A Google Play apps search page with the search in q. * **Example page:** [https://play.google.com/store/search?q=meditation\&c=apps](https://play.google.com/store/search?q=meditation\&c=apps) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `limit` (Return at most this many apps. You pay 1 credit per 10 returned). * **Price:** 1 credit per 10 apps. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "com.spotlightsix.zentimerlite2", > "url": "https://play.google.com/store/apps/details?id=com.spotlightsix.zentimerlite2", > "title": "Insight Timer - Meditation App", > "brand": "Insight Network Inc", > "description": "The world’s most popular wellness app.", > "price": { > "amount": 0, > "currency": "USD" > }, > "originalPrice": null, > "rating": 4.698212, > "reviewCount": null, > "availability": null, > "images": [], > "categories": [ > "Health & Fitness" > ], > "seller": { > "id": null, > "name": "Insight Network Inc", > "handle": null, > "url": null, > "avatarUrl": null > }, > "genre": "Health & Fitness", > "installsText": "10,000,000+", > "installsMin": 10000000, > "iconUrl": "https://play-lh.googleusercontent.com/H7MMtGtHuKqoT73wpfXXuqBgufaw3k03jUG58cqwJ1KITPU6nY8c1cvdAYCNcZY7xRwKwi-G3W6yltje3…" > } > ], > "cursor": null, > "page": null, > "total": null > } > ``` ## google-play-app A Google Play app page. * **Example page:** [https://play.google.com/store/apps/details?id=com.spotify.music](https://play.google.com/store/apps/details?id=com.spotify.music) * **Returns:** One product: `id`, `url`, `title`, `brand`, `description`, `price`, `originalPrice`, `rating`, `reviewCount`, `availability`, `images`, `categories`, `seller`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "com.spotify.music", > "url": "https://play.google.com/store/apps/details?id=com.spotify.music", > "title": "Spotify: Music and Podcasts", > "brand": "Spotify AB", > "description": "With the Spotify music and podcast app, you can play millions of songs, albums and original podcasts for free. We have…", > "price": { > "amount": 0, > "currency": "USD" > }, > "originalPrice": null, > "rating": 4.3492084, > "reviewCount": 36593987, > "availability": null, > "images": [ > "https://play-lh.googleusercontent.com/c1jnjL-9CIFlwlTMX3xNyeo8aEH39sNuC5zpTHhfW8keGxQE3TBMRX9Rm3VqM3E03Cyl9AqtnxuKvxJpc…", > "https://play-lh.googleusercontent.com/YxWsaNLSEBvLh04geMOADhSq6Ln5LmRrpa51ixZ7YkcEwmPQ-wdtnvoZDjVAgufbi2et0IlTVDAsvCCml…", > "https://play-lh.googleusercontent.com/RevDecVUzkc8iYhVazBoXb0O0Amy3_w6MNzzABHyAlyZjEYBq3xl-UxuxL5PGB6xTZpuxV7tET3pg1rp6…" > ], > "categories": [ > "Music & Audio" > ], > "seller": { > "id": "Spotify+AB", > "name": "Spotify AB", > "handle": null, > "url": "https://www.spotify.com", > "avatarUrl": null > }, > "summary": "Listen to songs, play podcasts, create playlists and discover music you'll love", > "developerEmail": "name@example.com", > "developerAddress": "Regeringsgatan 19\n111 53 Stockholm\nSweden", > "privacyPolicyUrl": "https://www.spotify.com/legal/privacy-policy/", > "genreId": "MUSIC_AND_AUDIO", > "genre": "Music & Audio", > "contentRating": "Teen", > "installsText": "1,000,000,000+", > "installsMin": 1000000000, > "installsExact": 3183142421, > "reviews": 1858224, > "ratingsOne": 3720805, > "ratingsTwo": 1068486, > "ratingsThree": 1310075, > "ratingsFour": 3106172, > "ratingsFive": 27388425, > "hasInAppPurchases": true, > "inAppPriceText": "$4.99 - $203.88 per item", > "hasAds": true, > "version": null, > "recentChanges": "We’re always making changes and improvements to Spotify. To make sure you don’t miss a thing, just keep your Updates…", > "releasedAt": "2014-05-27T13:12:17.000Z", > "updatedAt": "2026-11-02T11:59:56.000Z", > "iconUrl": "https://play-lh.googleusercontent.com/IzQgYCcnCFCD08GR-3bdtcT8xzOvrNkC84avGT5CwTX2VIqmTmKKJcP_Cd4JoBOdmCMlTndlOzV6hrthg…", > "bannerUrl": "https://play-lh.googleusercontent.com/WdedaGD6EAXZgy88wZM97aIcenQ5Cqzu_IUWBMMalkZmVe2lhv_3YqIUh-6pFqLv27kZ44cQX3qxyZTXH…" > } > ``` ## google-play-reviews A Google Play app page. * **Example page:** [https://play.google.com/store/apps/details?id=com.spotify.music](https://play.google.com/store/apps/details?id=com.spotify.music) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `sort`, `rating`, `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "c58d26d8-375d-43e9-9808-786a66f26a9b", > "url": "https://play.google.com/store/apps/details?id=com.spotify.music&reviewId=c58d26d8-375d-43e9-9808-786a66f26a9b", > "author": { > "id": null, > "name": "Logan Richardson", > "handle": null, > "url": null, > "avatarUrl": "https://play-lh.googleusercontent.com/a-/ALV-UjX2c91WA30EwkdfuUyShIThoBKVH5e73MeJBdASIeds-DeqSAr3" > }, > "rating": 5, > "title": null, > "text": "Has Ads. But Its Great 😊", > "publishedAt": "2026-11-03T23:01:14.000Z", > "likes": 0, > "response": null, > "subject": null, > "appVersion": "9.1.94.1929" > } > ], > "cursor": "Cs4BIsUBARqIumiznT7PDRWOeC0aggYPAVdlNu6PwtpW9Cp_IZPzgDi0LNGBx5TUepT9l8rwVWmIMvyGaaarLeoiaLGntaALlgK42P3RKN0HnhXTkBa78qmsxma9VFddGCKBO1GG-8EJnvEwv2dLHRbqSwueo...", > "page": null, > "total": null > } > ``` # Jobs Source: https://docs.stophy.dev/sources/jobs Search job listings on LinkedIn, Indeed, Upwork and company careers pages. Get the full posting for any job, and Glassdoor reviews and salaries. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.linkedin.com/jobs/search?keywords=software%20engineer&location=United%20States&f_TPR=r604800","formats":[{"type":"json","parser":"linkedin-jobs"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.linkedin.com/jobs/search?keywords=software%20engineer&location=United%20States&f_TPR=r604800", formats: [{ type: "json", parser: "linkedin-jobs" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.linkedin.com/jobs/search?keywords=software%20engineer&location=United%20States&f_TPR=r604800", "formats": [{"type": "json", "parser": "linkedin-jobs"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "linkedin-jobs", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`linkedin-jobs`](#linkedin-jobs) | A LinkedIn jobs search page with keywords, a location or a company filter. | 1 credit per call. | | [`linkedin-job`](#linkedin-job) | A LinkedIn job page or lnkd.in share link. | 1 credit per call. | | [`indeed-search`](#indeed-search) | An Indeed job search page with a search q or a place l, like indeed.com/jobs?q=nurse\&l=Austin,+TX. | 1 credit per call. | | [`indeed-job`](#indeed-job) | An Indeed job page with a jk key, like indeed.com/viewjob?jk=17c2d37519bd8374. | 1 credit per call. | | [`upwork-search`](#upwork-search) | An Upwork job search page, like upwork.com/nx/search/jobs/?q=react. | 1 credit per call. | | [`upwork-job`](#upwork-job) | An Upwork job page, like upwork.com/jobs/\~02... | 1 credit per call. | | [`careers-jobs`](#careers-jobs) | A company job board on Greenhouse, Lever, Ashby, Workday, Workable or SmartRecruiters, like boards.greenhouse.io/figma. | 1 credit per call. | | [`careers-job`](#careers-job) | One job on a company job board, like boards.greenhouse.io/figma/jobs/5426468004. | 1 credit per call. | | [`glassdoor-company`](#glassdoor-company) | A Glassdoor company page (overview, reviews or salaries). | 1 credit per call. | | [`glassdoor-reviews`](#glassdoor-reviews) | A Glassdoor company page (overview, reviews or salaries). | 1 credit per call. | | [`glassdoor-salaries`](#glassdoor-salaries) | A Glassdoor company page (overview, reviews or salaries). | 1 credit per call. | ## linkedin-jobs A LinkedIn jobs search page with keywords, a location or a company filter. * **Example page:** [https://www.linkedin.com/jobs/search?keywords=software%20engineer\&location=United%20States\&f\_TPR=r604800](https://www.linkedin.com/jobs/search?keywords=software%20engineer\&location=United%20States\&f_TPR=r604800) * **Returns:** A list of jobs: `results`, `cursor`, `page`, `total`. * **Options:** `company` (One company or up to five: LinkedIn URLs, slugs like google, or company ids), `easyApply` (LinkedIn's own Easy Apply), `fewApplicants` (LinkedIn's own Under 10 applicants), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "4476983365", > "url": "https://www.linkedin.com/jobs/view/4476983365", > "title": "Software Engineer II (Java/AWS)", > "company": { > "id": null, > "name": "JPMorganChase", > "url": "https://www.linkedin.com/company/jpmorganchase" > }, > "location": "New York, NY", > "isRemote": null, > "salary": null, > "employmentType": null, > "publishedAt": "2026-10-29T00:00:00.000Z", > "description": null, > "companyAvatarUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQGxpntCyRgsuA/company-logo_100_100/company-logo_100_100/0/1718711710850/jpmo…", > "salaryText": null, > "isEasyApply": null, > "insight": "Actively Hiring" > } > ], > "cursor": null, > "page": 1, > "total": null > } > ``` ## linkedin-job A LinkedIn job page or lnkd.in share link. * **Example page:** [https://www.linkedin.com/jobs/view/4476983365](https://www.linkedin.com/jobs/view/4476983365) * **Returns:** One job: `id`, `url`, `title`, `company`, `location`, `isRemote`, `salary`, `employmentType`, `publishedAt`, `description`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "4476983365", > "url": "https://www.linkedin.com/jobs/view/4476983365", > "title": "Software Engineer II (Java/AWS)", > "company": { > "id": null, > "name": "JPMorganChase", > "url": "https://www.linkedin.com/company/jpmorganchase" > }, > "location": "New York, NY", > "isRemote": null, > "salary": { > "min": 123500, > "max": 150000, > "currency": "USD", > "period": "year" > }, > "employmentType": "Full-time", > "publishedAt": "2026-10-29T00:00:00.000Z", > "description": "Job Description\n\nYou're ready to gain the skills and experience needed to grow within your role and advance your…", > "companyAvatarUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQGxpntCyRgsuA/company-logo_100_100/company-logo_100_100/0/1718711710850/jpmo…", > "salaryText": "$123,500.00/yr - $150,000.00/yr", > "isEasyApply": false, > "descriptionHtml": "Job Description

You're ready to gain the skills and experience needed to grow within your role…", > "applicants": 200, > "applicantsText": "Over 200 applicants", > "applyUrl": null, > "seniority": "Not Applicable", > "jobFunction": null, > "industries": "Financial Services" > } > ``` ## indeed-search An Indeed job search page with a search q or a place l, like indeed.com/jobs?q=nurse\&l=Austin,+TX. * **Example page:** [https://www.indeed.com/jobs?q=software+engineer\&l=Austin%2C+TX](https://www.indeed.com/jobs?q=software+engineer\&l=Austin%2C+TX) * **Returns:** A list of jobs: `results`, `cursor`, `page`, `total`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `distanceMiles` (Indeed's own Distance from the location. 0 is the exact location only), `datePosted` (Indeed's own Date posted. A relisted job keeps its first publishedAt and shows the new date in indexedAt), `remote` (Indeed's own Remote filter: Remote, or Hybrid work), `jobType` (Indeed's own Job type), `experienceLevel` (Indeed's own Experience level), `education` (Indeed's own Education), `sort` (Indeed's own Sort by), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "17c2d37519bd8374", > "url": "https://www.indeed.com/viewjob?jk=17c2d37519bd8374", > "title": "Software Engineer I", > "company": { > "id": null, > "name": "Indeed", > "url": "https://www.indeed.com/cmp/Indeed" > }, > "location": "Austin, TX", > "isRemote": false, > "salary": { > "min": 94000, > "max": 142000, > "currency": "USD", > "period": "year" > }, > "employmentType": "fullTime", > "publishedAt": "2026-09-18T05:00:00.000Z", > "description": "Our Mission\n\nAs the world’s number 1 job site*, our mission is to help people get jobs. We strive to cultivate an…", > "companyAvatarUrl": "https://d2q79iu7y748jz.cloudfront.net/s/_squarelogo/256x256/ff794fb897747bee7ebc1325d4b7a7da", > "companyWebsite": "https://www.indeed.com", > "companyIndustry": null, > "companyEmployeesText": "10,000+", > "companyRevenueText": "$1B to $5B (USD)", > "companyDescription": "We help people get jobs.", > "addressCity": "Austin", > "addressRegion": "TX", > "addressPostalCode": null, > "addressCountry": "US", > "latitude": 30.26715, > "longitude": -97.74306, > "salaryIsEstimate": false, > "isHybrid": false, > "experienceLevels": [ > "entry" > ], > "educationLevels": [], > "attributes": [ > "Computer science", > "Paid parental leave", > "Open paid time off" > ], > "indexedAt": "2026-09-18T20:03:11.779Z", > "applyUrl": "https://careers-indeed.icims.com/jobs/47665/job", > "isEasyApply": true, > "isUrgent": false, > "source": "Indeed" > } > ], > "cursor": "ABkAAYEAGQAAAAAAAAAAAAAAAmbw3gcAMwEAD//DeIZh97cKZHp8VdgaPf3oT+BsBrtxqEmz6srU+gRNQJJ7U2AgWQSXvJYRAk5IMgAA", > "page": null, > "total": null > } > ``` ## indeed-job An Indeed job page with a jk key, like indeed.com/viewjob?jk=17c2d37519bd8374. * **Example page:** [https://www.indeed.com/viewjob?jk=17c2d37519bd8374](https://www.indeed.com/viewjob?jk=17c2d37519bd8374) * **Returns:** One job: `id`, `url`, `title`, `company`, `location`, `isRemote`, `salary`, `employmentType`, `publishedAt`, `description`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > null > ``` ## upwork-search An Upwork job search page, like upwork.com/nx/search/jobs/?q=react. * **Example page:** [https://www.upwork.com/nx/search/jobs/?q=react\&sort=recency](https://www.upwork.com/nx/search/jobs/?q=react\&sort=recency) * **Returns:** A list of jobs: `results`, `cursor`, `page`, `total`. * **Options:** `jobType`, `experienceLevel`, `workload` (Upwork's hours needed: full time, part time, or as needed. Only hourly jobs say this, so the search stays hourly), `duration` (Upwork's project length: under one month, one to three months, three to six months, or more than six months. Only hourly jobs say this, so the search stays hourly), `minHourlyRate` (Lowest hourly rate in USD. A job matches when its posted range overlaps this minimum, so 25 to 50 matches a minimum of 50. The search stays hourly), `maxHourlyRate` (Highest hourly rate in USD. Send it with minHourlyRate. The job's posted range overlaps both, and the search stays hourly), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > null > ``` ## upwork-job An Upwork job page, like upwork.com/jobs/\~02... * **Example page:** [https://upwork.com/freelance-jobs/apply/React-Developer-Needed-for-Long-Term-Part-Time-Remote-Work\_\~022099839291870230198](https://upwork.com/freelance-jobs/apply/React-Developer-Needed-for-Long-Term-Part-Time-Remote-Work_~022099839291870230198) * **Returns:** One job: `id`, `url`, `title`, `company`, `location`, `isRemote`, `salary`, `employmentType`, `publishedAt`, `description`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > null > ``` ## careers-jobs A company job board on Greenhouse, Lever, Ashby, Workday, Workable or SmartRecruiters, like boards.greenhouse.io/figma. * **Example page:** [https://boards.greenhouse.io/figma](https://boards.greenhouse.io/figma) * **Returns:** A list of jobs: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "5813967004", > "url": "https://boards.greenhouse.io/figma/jobs/5813967004", > "title": "Distribution Partner Manager", > "company": null, > "location": "San Francisco, CA • New York, NY • United States", > "isRemote": null, > "salary": null, > "employmentType": null, > "publishedAt": "2026-02-28T00:00:43.000Z", > "description": null, > "department": "Business Development", > "team": null, > "updatedAt": "2026-10-27T17:40:12.000Z", > "postedText": null, > "boardUrl": "https://boards.greenhouse.io/figma", > "workplaceType": null > } > ], > "cursor": "20", > "page": null, > "total": null > } > ``` ## careers-job One job on a company job board, like boards.greenhouse.io/figma/jobs/5426468004. * **Example page:** [https://boards.greenhouse.io/figma/jobs/5426468004](https://boards.greenhouse.io/figma/jobs/5426468004) * **Returns:** One job: `id`, `url`, `title`, `company`, `location`, `isRemote`, `salary`, `employmentType`, `publishedAt`, `description`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "5426468004", > "url": "https://boards.greenhouse.io/figma/jobs/5426468004", > "title": "Account Executive, Enterprise", > "company": null, > "location": "San Francisco, CA • New York, NY • United States", > "isRemote": null, > "salary": { > "min": 165000, > "max": 190000, > "currency": "USD", > "period": null > }, > "employmentType": null, > "publishedAt": "2025-01-28T23:57:29.000Z", > "description": "Figma is growing our team of passionate creatives and builders on a mission to make design accessible to all. Figma’s…", > "department": "Sales", > "team": null, > "updatedAt": "2026-10-27T17:40:12.000Z", > "postedText": null, > "applyUrl": "https://boards.greenhouse.io/figma/jobs/5426468004?gh_jid=5426468004", > "boardUrl": "https://boards.greenhouse.io/figma", > "workplaceType": null > } > ``` ## glassdoor-company A Glassdoor company page (overview, reviews or salaries). * **Example page:** [https://www.glassdoor.com/Overview/Working-at-Google-EI\_IE9079.11,17.htm](https://www.glassdoor.com/Overview/Working-at-Google-EI_IE9079.11,17.htm) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "9079", > "url": "https://www.glassdoor.com/Overview/Working-at-Google-EI_IE9079.11,17.htm", > "handle": null, > "name": "Google", > "bio": null, > "avatarUrl": null, > "isVerified": null, > "followers": null, > "following": null, > "posts": null, > "website": "https://goo.gle/4ehVuXi", > "location": "Mountain View, CA", > "category": "Internet & Web Services", > "rating": 4.3, > "reviewCount": 74053, > "cultureRating": 4.2, > "workLifeBalanceRating": 4.2, > "payRating": 4.5, > "managementRating": 3.8, > "careerOpportunitiesRating": 4.1, > "recommendPercent": 87, > "ceoApprovalPercent": 83, > "size": "10000+ Employees" > } > ``` ## glassdoor-reviews A Glassdoor company page (overview, reviews or salaries). * **Example page:** [https://www.glassdoor.com/Overview/Working-at-Google-EI\_IE9079.11,17.htm](https://www.glassdoor.com/Overview/Working-at-Google-EI_IE9079.11,17.htm) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "106187953", > "url": null, > "author": null, > "rating": 4, > "title": "Murky but a good life at google", > "text": "Pros: Work/life, brand recognition is great\nCons: Poor vision in LCS tbh", > "publishedAt": "2026-11-02T00:00:00.000Z", > "likes": null, > "response": null, > "subject": { > "id": "9079", > "name": null, > "url": null > }, > "pros": "Work/life, brand recognition is great", > "cons": "Poor vision in LCS tbh", > "adviceToManagement": null, > "jobTitle": "Senior Analytical Lead", > "location": "Chicago, IL", > "employmentStatus": "regular" > } > ], > "cursor": null, > "page": 1, > "total": 68359, > "totalAllLanguages": 74053 > } > ``` ## glassdoor-salaries A Glassdoor company page (overview, reviews or salaries). * **Example page:** [https://www.glassdoor.com/Overview/Working-at-Google-EI\_IE9079.11,17.htm](https://www.glassdoor.com/Overview/Working-at-Google-EI_IE9079.11,17.htm) * **Returns:** `jobTitle`, `reports`, `totalPayMin`, `totalPayMedian`, `totalPayMax`, `basePayMin`. * **Options:** `country` (Country the pay is reported for, as its English name like India or Germany. Defaults to the United States), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "companyId": "9079", > "country": "United States", > "total": 9423, > "results": [ > { > "jobTitle": "Software Engineer", > "reports": 51622, > "totalPayMin": 242067, > "totalPayMedian": 287724, > "totalPayMax": 351875, > "basePayMin": 158856, > "basePayMedian": 176776, > "basePayMax": 196719, > "payCurrency": "USD", > "payPeriod": "year" > } > ], > "page": 1 > } > ``` # Places and travel Source: https://docs.stophy.dev/sources/places-and-travel Find places on Google Maps, Tripadvisor and Yelp, and search stays on Google Hotels, Airbnb, Booking.com and Expedia. Search flights and Luma events. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.google.com/maps/search/dentists+in+Ljubljana","formats":[{"type":"json","parser":"google-maps"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.google.com/maps/search/dentists+in+Ljubljana", formats: [{ type: "json", parser: "google-maps" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.google.com/maps/search/dentists+in+Ljubljana", "formats": [{"type": "json", "parser": "google-maps"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "google-maps", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`google-maps`](#google-maps) | A Google Maps search page that names a place after in, near or around. | 1 credit per call. | | [`google-maps-place`](#google-maps-place) | A Google Maps place page. | 1 credit per call. | | [`google-maps-reviews`](#google-maps-reviews) | A Google Maps place page. | 1 credit per 10 reviews. | | [`google-flights`](#google-flights) | A Google Flights search page, from the address bar or with a q of IATA airport codes and a date, like Flights to JFK from LHR on 2026-12-15. | 1 credit per call. | | [`google-hotels`](#google-hotels) | A Google Hotels page with a place in q, like hotels in Lisbon. | 1 credit per call. | | [`tripadvisor-search`](#tripadvisor-search) | A Tripadvisor search page, like tripadvisor.com/Search?q=ritz+london. | 1 credit per call. | | [`tripadvisor-place`](#tripadvisor-place) | A Tripadvisor hotel, restaurant or attraction page. | 1 credit per call. | | [`tripadvisor-reviews`](#tripadvisor-reviews) | A Tripadvisor hotel, restaurant or attraction page. | 1 credit per call. | | [`yelp-search`](#yelp-search) | A Yelp search page with both what and where, like yelp.com/search?find\_desc=pizza\&find\_loc=Austin%2C+TX. | 1 credit per call. | | [`yelp-business`](#yelp-business) | A Yelp business page, like yelp.com/biz/franklin-barbecue-austin. | 1 credit per call. | | [`yelp-reviews`](#yelp-reviews) | A Yelp business page, like yelp.com/biz/franklin-barbecue-austin. | 1 credit per call. | | [`booking-search`](#booking-search) | A Booking.com search results page with a place in ss, like booking.com/searchresults.html?ss=Lisbon. | 1 credit per call. | | [`booking-hotel`](#booking-hotel) | A Booking.com hotel page, like booking.com/hotel/pt/hf-fenix-urban.html. | 1 credit per call. | | [`booking-reviews`](#booking-reviews) | A Booking.com hotel page, like booking.com/hotel/pt/hf-fenix-urban.html. | 1 credit per call. | | [`expedia-hotels`](#expedia-hotels) | An Expedia hotel search page with a destination, like expedia.com/Hotel-Search?destination=Paris. | 1 credit per call. | | [`airbnb-search`](#airbnb-search) | An Airbnb search page for a place with checkin and checkout dates, like airbnb.com/s/Lisbon--Portugal/homes?checkin=2026-12-10\&checkout=2026-12-12. | 1 credit per call. | | [`airbnb-listing`](#airbnb-listing) | An Airbnb listing page, like airbnb.com/rooms/18249319. | 1 credit per call. | | [`airbnb-reviews`](#airbnb-reviews) | An Airbnb listing page, like airbnb.com/rooms/18249319. | 1 credit per call. | | [`luma-events`](#luma-events) | A Luma city page, like luma.com/sf or lu.ma/london. | 1 credit per call. | | [`luma-event`](#luma-event) | A Luma event page, like luma.com/nighthack. | 1 credit per call. | ## google-maps A Google Maps search page that names a place after in, near or around. * **Example page:** [https://www.google.com/maps/search/dentists+in+Ljubljana](https://www.google.com/maps/search/dentists+in+Ljubljana) * **Returns:** A list of places: `results`, `cursor`, `page`, `total`. * **Options:** `minRating`, `openNow` (Google Maps' own Hours filter, Open now: only places open at the moment of the search), `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `page` (Page number, starting at 1). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "0x47653296b2abdbc7:0x49588016d0bf3f31", > "url": "https://www.google.com/maps?cid=5285114998199107377", > "name": "OrthoDental", > "categories": [ > "Dentist", > "Dental clinic", > "Dental implants periodontist" > ], > "address": "Vilharjeva cesta 42, 1000 Ljubljana, Slovenia", > "location": { > "latitude": 46.0595907, > "longitude": 14.5190697 > }, > "phone": "+1 555 0100", > "website": "https://orthodental.si/", > "description": null, > "rating": 4.9, > "reviewCount": 845, > "priceLevel": null, > "hours": [ > { > "days": "Thursday", > "times": [ > "7 AM-8 PM" > ] > } > ], > "images": [ > "https://lh3.googleusercontent.com/grass-cs/AABkmLdBhaKXYHqK_5Aj1bnahBGOIT1sRrAAJnXe3Rmn96rrVp4oGovG0IIlCy2N9ZA74ppszS7_…" > ], > "googlePlaceId": "ChIJx9urspYyZUcRMT-_0BaAWEk", > "photos": 57, > "hoursToday": "7 AM-8 PM", > "openStatus": "Closed · Opens 7 AM", > "timezone": "Europe/Ljubljana", > "reservationUrl": null, > "attributes": [ > "Wheelchair accessible entrance", > "Wheelchair accessible parking lot", > "Wheelchair accessible restroom" > ] > } > ], > "cursor": null, > "page": 1, > "total": null > } > ``` ## google-maps-place A Google Maps place page. * **Example page:** [https://www.google.com/maps/place/Eiffel+Tower/@48.8584,2.2945,17z/data=!3m1!4b1!4m6!3m5!1s0x47e66e2964e34e2d:0x8ddca9ee380ef7e0](https://www.google.com/maps/place/Eiffel+Tower/@48.8584,2.2945,17z/data=!3m1!4b1!4m6!3m5!1s0x47e66e2964e34e2d:0x8ddca9ee380ef7e0) * **Returns:** One place: `id`, `url`, `name`, `categories`, `address`, `location`, `phone`, `website`, `description`, `rating`, `reviewCount`, `priceLevel`, `hours`, `images`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0", > "url": "https://www.google.com/maps?cid=10222232094831998944", > "name": "Eiffel Tower", > "categories": [ > "Historical landmark", > "Monument", > "Tourist attraction" > ], > "address": "Av. Gustave Eiffel, 75007 Paris, France", > "location": { > "latitude": 48.858370099999995, > "longitude": 2.2944812999999997 > }, > "phone": null, > "website": "https://www.toureiffel.paris/fr", > "description": "Gustave Eiffel's iconic, wrought-iron 1889 tower, with steps and elevators to observation decks.", > "rating": 4.7, > "reviewCount": 499973, > "priceLevel": null, > "hours": [ > { > "days": "Thursday", > "times": [ > "9 AM-12 AM" > ] > } > ], > "images": [ > "https://lh3.googleusercontent.com/grass-cs/AABkmLdQDdsOsH9WSc8SkiOuMHCC-IdIUZhRh4kDmNWte1b_k3tDK810QX1NVW0k5Y9n5sij1YH8…" > ], > "googlePlaceId": "ChIJLU7jZClu5kcR4PcOOO6p3I0", > "photos": 1717839, > "hoursToday": "9 AM-12 AM", > "openStatus": "Closed · Opens 9 AM", > "timezone": "Europe/Paris", > "plusCode": "8FW4V75V+8Q", > "reservationUrl": null, > "attributes": [ > "Wheelchair accessible entrance", > "Wheelchair accessible parking lot", > "Wheelchair accessible restroom" > ] > } > ``` ## google-maps-reviews A Google Maps place page. * **Example page:** [https://www.google.com/maps/place/Eiffel+Tower/@48.8584,2.2945,17z/data=!3m1!4b1!4m6!3m5!1s0x47e66e2964e34e2d:0x8ddca9ee380ef7e0](https://www.google.com/maps/place/Eiffel+Tower/@48.8584,2.2945,17z/data=!3m1!4b1!4m6!3m5!1s0x47e66e2964e34e2d:0x8ddca9ee380ef7e0) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `sort`, `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `limit` (Return at most this many reviews. You pay 1 credit per 10 returned), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per 10 reviews. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "Ci9DQUlRQUNvZENodHljRjlvT21SdFFpMWllVlYwUVZwbVVHUjJVbHBCVmpOamRFRRAB", > "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT21SdFFpMWllVlYwUVZwbVVHUjJVbHBCVm…", > "author": { > "id": "114431275563417848290", > "name": "Abubakir Sldlql", > "handle": null, > "url": "https://www.google.com/maps/contrib/114431275563417848290/reviews?hl=en-GB", > "avatarUrl": "https://lh3.googleusercontent.com/a/ACg8ocKzoJXQl9O1IxdAdtfYqMW_JdPWQfI2LoIvi3whGl1YpN33qQ=s64-c-rp-mo-br100" > }, > "rating": 1, > "title": null, > "text": null, > "publishedAt": "2026-11-04T22:13:17.846Z", > "likes": null, > "response": null, > "subject": null, > "language": null, > "authorReviews": 0, > "authorPhotos": 0, > "authorIsLocalGuide": false, > "imageUrls": [], > "details": [] > } > ], > "cursor": "Ci8IARInCgoAP72F5XxPbG__EhB-y9zFqnuTEO83mU0AAAAAGgf_Al5XxPbGGAAiAA", > "page": null, > "total": null > } > ``` ## google-flights A Google Flights search page, from the address bar or with a q of IATA airport codes and a date, like Flights to JFK from LHR on 2026-12-15. * **Example page:** [https://www.google.com/travel/flights?q=Flights%20to%20JFK%20from%20LHR%20on%202026-12-15](https://www.google.com/travel/flights?q=Flights%20to%20JFK%20from%20LHR%20on%202026-12-15) * **Returns:** `isBest`, `price`, `priceCurrency`, `airlines`, `stops`, `durationSeconds`. * **Options:** `returnDate`, `adults`, `cabin`, `currency` (ISO 4217 currency code, e.g. USD), `stops` (Google Flights' Stops filter), `airlines` (Google Flights' Airlines filter, as airline codes like KQ or EK), `carryOnBags` (Google Flights' Bags filter: prices include this many carry-on bags), `checkedBags` (Google Flights' Bags filter: prices include this many checked bags), `maxPrice` (Google Flights' Price filter, in currency for all adults), `departureTime` (Google Flights' Times filter for the outbound departure), `arrivalTime` (Google Flights' Times filter for the outbound arrival), `maxDurationHours` (Google Flights' Duration filter). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "cabin": "economy", > "tripType": "oneWay", > "adults": 1, > "url": "https://www.google.com/travel/flights/search?tfs=GhoSCjIwMjYtMTItMTVqBRIDTEhScgUSA0pGS0ABSAGYAQI%3D&tfu=EgQIABABIgA&hl=…", > "results": [ > { > "isBest": true, > "price": 406, > "priceCurrency": "USD", > "airlines": [ > "SWISS" > ], > "stops": 1, > "durationSeconds": 44100, > "departureLocalTime": "2026-12-15T06:00", > "arrivalLocalTime": "2026-12-15T13:15", > "legs": [ > { > "flightNumber": "LX 345", > "airline": "SWISS", > "originCode": "LHR", > "originName": "Heathrow Airport", > "destinationCode": "ZRH", > "destinationName": "Zurich Airport", > "departureLocalTime": "2026-12-15T06:00", > "arrivalLocalTime": "2026-12-15T08:40", > "durationSeconds": 6000, > "aircraft": "Airbus A320neo", > "legroom": "29 inches" > } > ], > "layovers": [ > { > "airport": "ZRH", > "name": "Zurich Airport", > "city": "Zürich", > "durationSeconds": 4500 > } > ], > "emissionsGrams": 381000, > "typicalEmissionsGrams": 346000 > } > ] > } > ``` ## google-hotels A Google Hotels page with a place in q, like hotels in Lisbon. * **Example page:** [https://www.google.com/travel/search?q=hotels%20in%20Lisbon](https://www.google.com/travel/search?q=hotels%20in%20Lisbon) * **Returns:** `name`, `hotelId`, `hotelUrl`, `price`, `totalPrice`, `priceCurrency`. * **Options:** `checkIn` (Defaults to tomorrow), `checkOut` (Defaults to one night after checkIn), `adults`, `childrenAges` (One age per child, like \[7, 12]), `currency` (ISO 4217 currency code, e.g. USD), `minPrice` (Per night), `maxPrice` (Per night), `minRating` (Google Hotels' own Guest rating), `hotelClass` (Google Hotels' own Hotel class, as star counts like \[4, 5]), `amenities` (Google Hotels' own Amenities. Every one must be offered), `propertyTypes` (Google Hotels' own Property type), `freeCancellation`, `specialOffers`, `sort`, `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "checkIn": "2026-11-05", > "checkOut": "2026-11-06", > "results": [ > { > "name": "Lisboa Pessoa Hotel", > "hotelId": "ChoIh4uhruDksvGAARoNL2cvMTFjMXMzZHQ5dBAB", > "hotelUrl": "https://www.google.com/travel/hotels/entity/ChoIh4uhruDksvGAARoNL2cvMTFjMXMzZHQ5dBAB?hl=en&gl=us&curr=USD&ts=CAESCgoCCA…", > "price": 130, > "totalPrice": 142, > "priceCurrency": "USD", > "deal": "GREAT DEAL", > "dealDescription": "39% less than usual", > "rating": 4.7, > "reviews": 1545, > "hotelClass": 4, > "amenities": [ > "Breakfast ($)", > "Free Wi-Fi", > "Parking ($)" > ], > "position": 1 > } > ], > "cursor": "eyJvZmZzZXQiOjE4LCJzZWVuIjpbIkNob0loNHVocnVEa3N2R0FBUm9OTDJjdk1URmpNWE16WkhRNWRCQUIiLCJDaGtJNjhtUXRLaW9ncElfR2cwdlp5OHhNV051WWpONWRIRXdFQUUiLCJDaG9JN1pTN2pib..." > } > ``` ## tripadvisor-search A Tripadvisor search page, like tripadvisor.com/Search?q=ritz+london. * **Example page:** [https://www.tripadvisor.com/Search?q=ritz+london\&ssrc=h](https://www.tripadvisor.com/Search?q=ritz+london\&ssrc=h) * **Returns:** A list of places: `results`, `cursor`, `page`, `total`. * **Options:** `location`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "187591", > "url": "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html", > "name": "The Ritz London Hotel", > "categories": [ > "accommodation" > ], > "address": "150 Piccadilly", > "location": { > "latitude": 51.507088, > "longitude": -0.141628 > }, > "phone": null, > "website": null, > "description": null, > "rating": null, > "reviewCount": null, > "priceLevel": null, > "hours": [], > "images": [ > "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/33/be/ef/d4/the-ritz-london-entrance.jpg?w=1200&h=900&s=1" > ], > "type": "accommodation", > "parent": "London, England" > } > ], > "cursor": null, > "page": null, > "total": null > } > ``` ## tripadvisor-place A Tripadvisor hotel, restaurant or attraction page. * **Example page:** [https://www.tripadvisor.com/Hotel\_Review-g186338-d187591-Reviews-The\_Ritz\_London\_Hotel-London\_England.html](https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html) * **Returns:** One place: `id`, `url`, `name`, `categories`, `address`, `location`, `phone`, `website`, `description`, `rating`, `reviewCount`, `priceLevel`, `hours`, `images`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > null > ``` ## tripadvisor-reviews A Tripadvisor hotel, restaurant or attraction page. * **Example page:** [https://www.tripadvisor.com/Hotel\_Review-g186338-d187591-Reviews-The\_Ritz\_London\_Hotel-London\_England.html](https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `language`, `ratings`, `travelerTypes` (Tripadvisor's own Traveler type filter: families, couples, solo, business or friends. Only reviews from these travelers), `months` (Tripadvisor's own Time of year filter: marMay, junAug, sepNov or decFeb. Only reviews written in these months of the year), `sort` (Tripadvisor's own Sort by: mostRecent (Most recent) or detailed (Detailed reviews, ordered by recency and how much they say)), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "1082705333", > "url": "https://www.tripadvisor.com/ShowUserReviews-g186338-d187591-r1082705333-The_Ritz_London_Hotel-London_England.html", > "author": { > "id": null, > "name": "Richard P", > "handle": "G5474DTrichardk", > "url": "https://www.tripadvisor.com/Profile/G5474DTrichardk", > "avatarUrl": null > }, > "rating": 5, > "title": "Great place", > "text": "Brilliant everything doorman super cool receptionist bit moody", > "publishedAt": "2026-10-21T00:00:00.000Z", > "likes": 0, > "response": { > "text": "Dear G5474DTrichardk,\n\nWe are delighted to read that you enjoyed your experience with us. However, we are sorry to…", > "publishedAt": "2026-10-22T00:00:00.000Z" > }, > "subject": { > "id": "187591", > "name": "The Ritz London Hotel", > "url": "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html" > }, > "ownerReplyAuthor": "General Manager", > "language": "en", > "stayMonth": "2026-10", > "tripType": "friends", > "subRatings": [ > { > "name": "Value", > "rating": 3 > } > ], > "authorAddress": "Sotogrande, Spain", > "authorContributions": 88 > } > ], > "cursor": null, > "page": 1, > "total": 4965 > } > ``` ## yelp-search A Yelp search page with both what and where, like yelp.com/search?find\_desc=pizza\&find\_loc=Austin%2C+TX. * **Example page:** [https://www.yelp.com/search?find\_desc=plumber\&find\_loc=Austin%2C+TX](https://www.yelp.com/search?find_desc=plumber\&find_loc=Austin%2C+TX) * **Returns:** A list of places: `results`, `cursor`, `page`, `total`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "TVHztfQAJUIaJDgdJuke-g", > "url": "https://www.yelp.com/biz/blue-dragon-plumbing-austin-2", > "name": "Blue Dragon Plumbing", > "categories": [ > "Plumbing" > ], > "address": "Austin", > "location": null, > "phone": null, > "website": null, > "description": null, > "rating": 4.9, > "reviewCount": 532, > "priceLevel": null, > "hours": [], > "images": [], > "businessAlias": "blue-dragon-plumbing-austin-2", > "addressStreet": null, > "addressCity": "Austin" > } > ], > "cursor": null, > "page": null, > "total": null > } > ``` ## yelp-business A Yelp business page, like yelp.com/biz/franklin-barbecue-austin. * **Example page:** [https://www.yelp.com/biz/franklin-barbecue-austin](https://www.yelp.com/biz/franklin-barbecue-austin) * **Returns:** One place: `id`, `url`, `name`, `categories`, `address`, `location`, `phone`, `website`, `description`, `rating`, `reviewCount`, `priceLevel`, `hours`, `images`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "MGzro82Fi4LYvc86acoONQ", > "url": "https://www.yelp.com/biz/franklin-barbecue-austin", > "name": "Franklin Barbecue", > "categories": [ > "Barbeque" > ], > "address": "900 E 11th St, Austin, TX 78702", > "location": { > "latitude": 30.2701348, > "longitude": -97.73134511 > }, > "phone": "+1 555 0100", > "website": "https://franklinbbq.com", > "description": null, > "rating": 4.5, > "reviewCount": 6495, > "priceLevel": "$$$", > "hours": [ > { > "days": "Mon", > "times": [ > "Closed" > ] > } > ], > "images": [], > "businessAlias": "franklin-barbecue-austin", > "addressStreet": "900 E 11th St", > "addressCity": "Austin", > "addressRegion": "TX", > "addressPostalCode": "78702", > "addressCountry": "US", > "neighborhoods": [ > "East Austin" > ], > "photosAndVideos": 8635, > "isClaimed": true > } > ``` ## yelp-reviews A Yelp business page, like yelp.com/biz/franklin-barbecue-austin. * **Example page:** [https://www.yelp.com/biz/franklin-barbecue-austin?sort\_by=date\_desc](https://www.yelp.com/biz/franklin-barbecue-austin?sort_by=date_desc) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "Wtxnb99DEKuOQtZ9Yd5qTw", > "url": "https://www.yelp.com/biz/franklin-barbecue-austin?hrid=Wtxnb99DEKuOQtZ9Yd5qTw", > "author": { > "id": "pOeu-5wB-A8kRcjJ1SWrdw", > "name": "Jen I.", > "handle": null, > "url": "https://www.yelp.com/user_details?userid=pOeu-5wB-A8kRcjJ1SWrdw", > "avatarUrl": null > }, > "rating": 5, > "title": null, > "text": "This was a bucket list resteraunt for us to try, we had some extra time and were in town so we had to try it out. \n\nWe…", > "publishedAt": "2026-11-02T20:42:12.000Z", > "likes": null, > "response": null, > "subject": { > "id": "MGzro82Fi4LYvc86acoONQ", > "name": "Franklin Barbecue", > "url": "https://www.yelp.com/biz/franklin-barbecue-austin" > }, > "language": "en", > "authorReviews": 115 > } > ], > "cursor": null, > "page": 1, > "total": 6480 > } > ``` ## booking-search A Booking.com search results page with a place in ss, like booking.com/searchresults.html?ss=Lisbon. * **Example page:** [https://www.booking.com/searchresults.html?ss=Lisbon\&checkin=2026-12-10\&checkout=2026-12-12\&group\_adults=2\&no\_rooms=1](https://www.booking.com/searchresults.html?ss=Lisbon\&checkin=2026-12-10\&checkout=2026-12-12\&group_adults=2\&no_rooms=1) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `currency` (ISO 4217 currency code, e.g. USD), `sort` (Booking.com's own Sort by: relevance (Our top picks) or distance (closest to the center of the place first)), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "9098389", > "url": "https://www.booking.com/hotel/pt/eurostas-lisboa-baixa.html", > "title": "Eurostars Lisboa Baixa", > "description": null, > "price": { > "amount": 131.75, > "currency": "USD" > }, > "pricePeriod": "night", > "status": null, > "address": "Rua de Prata, 88-114", > "location": { > "latitude": 38.710131, > "longitude": -9.136478 > }, > "bedrooms": null, > "bathrooms": null, > "area": null, > "propertyType": null, > "rating": 4.6, > "reviewCount": 1834, > "images": [ > "https://cf.bstatic.com/xdata/images/hotel/square600/425895275.jpg?k=eb4c9000683d7cdc25d9ecd4d321a30c9560b3a6183dde24632…" > ], > "host": null, > "position": 1, > "stars": 4, > "city": "Lisboa", > "countryCode": "pt", > "distanceText": "0.3 miles from downtown", > "hasFreeCancellation": false, > "neighborhood": "Santa Maria Maior, Lisbon", > "nights": 2, > "totalPrice": { > "amount": 263.5, > "currency": "USD" > }, > "taxesAndFees": { > "amount": 33.79, > "currency": "USD" > }, > "originalPrice": { > "amount": 439.16, > "currency": "USD" > } > } > ], > "cursor": "eyJvZmZzZXQiOjI1LCJzZWVuIjpbOTA5ODM4OSwyMzY3NjcsMzkzODIsMjM3NTAxLDQ5NjgyLDI4MzcyNTEsMzE1NDQyLDE0MDQ5MzQ2LDM5ODMzLDE5NzQ5MzcsMzc0NzU2NSwxMDQ0NTAxLDQxNzQ4MCw5O...", > "page": null, > "total": 3772, > "place": "Lisbon", > "checkIn": "2026-12-10", > "checkOut": "2026-12-12" > } > ``` ## booking-hotel A Booking.com hotel page, like booking.com/hotel/pt/hf-fenix-urban.html. * **Example page:** [https://www.booking.com/hotel/pt/hf-fenix-urban.html](https://www.booking.com/hotel/pt/hf-fenix-urban.html) * **Returns:** One listing: `id`, `url`, `title`, `description`, `price`, `pricePeriod`, `status`, `address`, `location`, `bedrooms`, `bathrooms`, `area`, `propertyType`, `rating`, `reviewCount`, `images`, `host`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "179501", > "url": "https://www.booking.com/hotel/pt/hf-fenix-urban.html", > "title": "HF Fénix Urban", > "description": "Centrally located in Lisbon, the HF Fénix Urban is a modern 4-star nonsmoking hotel offering free Wi-Fi and…", > "price": null, > "pricePeriod": "night", > "status": null, > "address": "Avenida Antonio Augusto De Aguiar,14, Avenidas Novas, 1050-016 Lisbon, Portugal", > "location": { > "latitude": 38.7287525576462, > "longitude": -9.149000197649 > }, > "bedrooms": null, > "bathrooms": null, > "area": null, > "propertyType": "hotel", > "rating": 4.35, > "reviewCount": 2463, > "images": [ > "https://cf.bstatic.com/xdata/images/hotel/max1024x768/351732850.jpg?k=dbeeb7b9acf72e3c4be78fc36c2fa5eb12c3d3ee0012a27bc…", > "https://cf.bstatic.com/xdata/images/hotel/max1024x768/778806252.jpg?k=3325ffa8f65107252c89e6b8f2d8d215a2867cdc4ffb2df98…", > "https://cf.bstatic.com/xdata/images/hotel/max1024x768/814912825.jpg?k=81eab4c647a17b920393c7ae8c7eaed47015e36e1214e32ae…" > ], > "host": null, > "stars": 4, > "addressStreet": "Avenida Antonio Augusto De Aguiar,14", > "addressCity": "Lisbon", > "addressCountryCode": "pt", > "checkInFrom": "3:00 PM", > "checkOutUntil": "12:00 PM", > "facilities": [ > { > "group": "General", > "name": "Air conditioning" > } > ], > "rooms": [ > { > "roomId": "17950102", > "name": "Comfort Queen", > "sizeSquareMeters": 12, > "description": "Located between the 1st and 12th floor, this comfort room features a white modern décor, flat-screen TV and mini-bar.…" > } > ], > "scores": [ > { > "category": "Staff", > "rating": 4.5 > } > ] > } > ``` ## booking-reviews A Booking.com hotel page, like booking.com/hotel/pt/hf-fenix-urban.html. * **Example page:** [https://www.booking.com/hotel/pt/hf-fenix-urban.html](https://www.booking.com/hotel/pt/hf-fenix-urban.html) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `sort` (Booking.com's own Sort reviews by: newest, mostRelevant or lowestScore (lowest scores first). Only newest pages without gaps. The other orders change between requests, so a walk through the pages can miss reviews), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "2af60057e6609d9a", > "url": null, > "author": null, > "rating": 5, > "title": null, > "text": "La ubicación y la cercanía del medio de trasporte", > "publishedAt": "2026-11-04T13:15:43.000Z", > "likes": null, > "response": null, > "subject": { > "id": "179501", > "name": null, > "url": null > }, > "language": "es", > "travelerType": "Couple", > "authorCountryCode": "es", > "roomName": "Economy Double or Twin Room", > "nights": 3, > "checkIn": "2026-10-31", > "checkOut": "2026-11-03", > "positiveText": "La ubicación y la cercanía del medio de trasporte", > "negativeText": null > } > ], > "cursor": "eyJvZmZzZXQiOjI1LCJzZWVuIjpbIjJhZjYwMDU3ZTYiLCI0ZjViYWQ4MmVlIiwiNDdiZjQ0ZGU5ZSIsIjZmZmRmOWYwMzQiLCIyZDcyOTBjZGJiIiwiODJhNzM0MDU4MCIsIjg4NTM1ODBlNzYiLCJhZDU4M...", > "page": null, > "total": 2463 > } > ``` ## expedia-hotels An Expedia hotel search page with a destination, like expedia.com/Hotel-Search?destination=Paris. * **Example page:** [https://www.expedia.com/Hotel-Search?destination=Paris\&startDate=2026-12-10\&endDate=2026-12-12\&adults=2](https://www.expedia.com/Hotel-Search?destination=Paris\&startDate=2026-12-10\&endDate=2026-12-12\&adults=2) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `sort` (Expedia's own sort: relevance (Recommended), priceLow (lowest price first) or rating (guest rating)), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "9619719", > "url": "https://www.expedia.com/Paris-Hotels-Hotel-De-Roubaix.h9619719.Hotel-Information?chkin=2026-12-10&chkout=2026-12-12&rm1…", > "title": "Hotel de Roubaix", > "description": null, > "price": { > "amount": 193, > "currency": "USD" > }, > "pricePeriod": "night", > "status": null, > "address": null, > "location": null, > "bedrooms": null, > "bathrooms": null, > "area": null, > "propertyType": null, > "rating": 4.7, > "reviewCount": 1581, > "images": [ > "https://images.trvl-media.com/lodging/10000000/9620000/9619800/9619719/7f5c6c38.jpg?impolicy=resizecrop&ra=fit&rw=455&r…" > ], > "host": null, > "neighborhood": "Paris", > "ratingText": "Exceptional", > "totalPrice": { > "amount": 438, > "currency": "USD" > }, > "totalPriceBefore": { > "amount": 564, > "currency": "USD" > } > } > ], > "cursor": null, > "page": null, > "total": 482 > } > ``` ## airbnb-search An Airbnb search page for a place with checkin and checkout dates, like airbnb.com/s/Lisbon--Portugal/homes?checkin=2026-12-10\&checkout=2026-12-12. * **Example page:** [https://www.airbnb.com/s/Lisbon--Portugal/homes?checkin=2026-12-10\&checkout=2026-12-12\&adults=2](https://www.airbnb.com/s/Lisbon--Portugal/homes?checkin=2026-12-10\&checkout=2026-12-12\&adults=2) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `minPrice` (Airbnb's own price range minimum: the nightly price after discounts and before taxes, in currency), `maxPrice` (Airbnb's own price range maximum: the nightly price after discounts and before taxes, in currency), `roomType` (Airbnb's own Type of place filter: entireHome (Entire home) or privateRoom (Room)), `currency` (Currency of every price in the answer and of minPrice and maxPrice), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "635404000587905839", > "url": "https://www.airbnb.com/rooms/635404000587905839", > "title": "Standard Studio with AC and Private bathroom", > "description": null, > "price": { > "amount": 68.36, > "currency": "USD" > }, > "pricePeriod": "night", > "status": null, > "address": "Lisbon", > "location": { > "latitude": 38.7193, > "longitude": -9.1572 > }, > "bedrooms": null, > "bathrooms": null, > "area": null, > "propertyType": "Apartment", > "rating": 4.92, > "reviewCount": 350, > "images": [ > "https://a0.muscache.com/im/pictures/miso/Hosting-635404000587905839/original/3131351e-96cc-4756-b74c-f644f5151efe.jpeg", > "https://a0.muscache.com/im/pictures/miso/Hosting-635404000587905839/original/4a866961-2a6a-4cdd-9bde-dbe3fa76be06.jpeg", > "https://a0.muscache.com/im/pictures/miso/Hosting-635404000587905839/original/65558c53-5aee-4d4d-8e4e-d7872c2e81bb.jpeg" > ], > "host": null, > "badges": [ > "Guest favorite" > ], > "totalPrice": { > "amount": 154.66, > "currency": "USD" > }, > "priceBeforeDiscount": { > "amount": 170.64, > "currency": "USD" > } > } > ], > "cursor": "eyJzZWN0aW9uX29mZnNldCI6MCwiaXRlbXNfb2Zmc2V0IjoxOCwidmVyc2lvbiI6MX0=~82f73074-e148-48f7-b3a3-d0c1f5fefc9e~1793832342_EAMmM5MDBmNjE4Zm~4tsfx44wwpwv.csstjkeoah...", > "page": null, > "total": null, > "location": "Lisbon, Portugal" > } > ``` ## airbnb-listing An Airbnb listing page, like airbnb.com/rooms/18249319. * **Example page:** [https://www.airbnb.com/rooms/18249319](https://www.airbnb.com/rooms/18249319) * **Returns:** One listing: `id`, `url`, `title`, `description`, `price`, `pricePeriod`, `status`, `address`, `location`, `bedrooms`, `bathrooms`, `area`, `propertyType`, `rating`, `reviewCount`, `images`, `host`. * **Options:** `checkIn` (First night, as YYYY-MM-DD. Send it with checkOut to get the price), `checkOut` (Day you leave, as YYYY-MM-DD. Send it with checkIn to get the price), `guests` (Number of guests. Only stays that fit this many), `currency` (Currency of every price in the answer and of minPrice and maxPrice). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "18249319", > "url": "https://www.airbnb.com/rooms/18249319", > "title": "Boutique Flat Cris do Carmo", > "description": "Located in the trendy, buzzing, and historic neighborhood of Chiado, this one-bedroom flat is both cozy and stylish,…", > "price": null, > "pricePeriod": "night", > "status": null, > "address": "Lisbon, Portugal", > "location": { > "latitude": 38.71345, > "longitude": -9.14014 > }, > "bedrooms": 1, > "bathrooms": 1, > "area": null, > "propertyType": "Entire rental unit", > "rating": 4.88, > "reviewCount": 432, > "images": [ > "https://a0.muscache.com/im/pictures/502c9731-ade7-4661-ad6b-bf8d7f11a039.jpg", > "https://a0.muscache.com/im/pictures/1cfb830e-c5a2-4653-aa4e-7763183827f5.jpg", > "https://a0.muscache.com/im/pictures/36e150aa-079b-4732-b616-da4e48256e15.jpg" > ], > "host": { > "id": null, > "name": "GestHomes By Alexandra & Pedro", > "handle": null, > "url": null, > "avatarUrl": null, > "isSuperhost": true > }, > "guests": 2, > "beds": 2, > "amenities": [ > "Hair dryer", > "Cleaning products", > "Shampoo" > ], > "isGuestFavorite": true, > "ratingAccuracy": 4.87, > "ratingCheckin": 4.88, > "ratingCleanliness": 4.92, > "ratingCommunication": 4.92, > "ratingLocation": 4.96, > "ratingValue": 4.78, > "houseRules": [ > "Up to 2 overnight guests", > "No pets", > "No smoking: Including vaping and e-cigarettes" > ], > "isAvailable": null, > "totalPrice": null, > "priceBeforeDiscount": null > } > ``` ## airbnb-reviews An Airbnb listing page, like airbnb.com/rooms/18249319. * **Example page:** [https://www.airbnb.com/rooms/18249319](https://www.airbnb.com/rooms/18249319) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "1807210451071666201", > "url": null, > "author": { > "id": null, > "name": "Magali", > "handle": null, > "url": null, > "avatarUrl": null > }, > "rating": 5, > "title": null, > "text": "Logement très agréable, très propre avec tous les équipements nécessaires pour les courts séjours. Literie et linge de…", > "publishedAt": "2026-10-29T11:24:33.000Z", > "likes": null, > "response": { > "text": "Merci beaucoup, Magali, pour ce retour élogieux ! Nous sommes ravis que vous ayez apprécié le confort et la propreté…", > "publishedAt": null > }, > "subject": { > "id": "18249319", > "name": null, > "url": "https://www.airbnb.com/rooms/18249319" > }, > "language": "fr", > "translatedText": "Very nice accommodation, very clean with all the amenities needed for short stays. Spotless bedding and linens.\nIdeal…", > "stayNote": "Stayed a few nights" > } > ], > "cursor": null, > "page": 1, > "total": 432 > } > ``` ## luma-events A Luma city page, like luma.com/sf or lu.ma/london. * **Example page:** [https://luma.com/sf](https://luma.com/sf) * **Returns:** A list of events: `results`, `cursor`, `page`, `total`. * **Options:** `category` (Only events in this Luma category), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "evt-Wh9NlYi9GwQqF2J", > "url": "https://luma.com/wkt3e8lq", > "title": "FORWARD - WOMEN'S HEALTH SUMMIT", > "description": null, > "startsAt": "2026-11-04T17:30:00.000Z", > "endsAt": "2026-11-04T23:30:00.000Z", > "timezone": "America/Los_Angeles", > "isOnline": false, > "address": "SVB Experience Center, 532 Market St, San Francisco, CA 94104, USA", > "location": { > "latitude": 37.7905863, > "longitude": -122.40033319999998 > }, > "price": null, > "hosts": [ > { > "id": null, > "name": "TechThrive Ventures", > "handle": null, > "url": null, > "avatarUrl": null > } > ], > "images": [ > "https://images.lumacdn.com/uploads/02/e46677f2-8725-4293-8f29-9ffa8c66520b.jpg" > ], > "city": "San Francisco, CA", > "calendarName": "Personal", > "guestCount": 0, > "isFree": true, > "isSoldOut": true, > "spotsRemaining": 0, > "needsApproval": true, > "hasWaitlist": true > } > ], > "cursor": "eyJzdiI6IjIwMjYtMTEtMDUgMDE6MzA6MDArMDAiLCJmYiI6ImV2dC1aRHVxZ2lVMzdrcDRCWnAifQ", > "page": null, > "total": null, > "city": "San Francisco" > } > ``` ## luma-event A Luma event page, like luma.com/nighthack. * **Example page:** [https://luma.com/nighthack](https://luma.com/nighthack) * **Returns:** One event: `id`, `url`, `title`, `description`, `startsAt`, `endsAt`, `timezone`, `isOnline`, `address`, `location`, `price`, `hosts`, `images`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "evt-BQrIrfoOg0genkv", > "url": "https://luma.com/nighthack", > "title": "Night Hack by Founders, Inc.", > "description": "Night Hack is back at Founders, Inc. on October 30.\n\nCome make something you want to show off. A robot. An agent. A…", > "startsAt": "2026-10-30T23:00:00.000Z", > "endsAt": "2026-10-31T06:00:00.000Z", > "timezone": "America/Los_Angeles", > "isOnline": false, > "address": null, > "location": { > "latitude": 37.80902842340874, > "longitude": -122.43129988976843 > }, > "price": null, > "hosts": [ > { > "id": null, > "name": "Adrianna Lakatos", > "handle": null, > "url": null, > "avatarUrl": null > } > ], > "images": [ > "https://images.lumacdn.com/event-covers/r1/24ead38c-7d9b-48bf-a3ff-24e7a74c0398.png" > ], > "city": "San Francisco, CA", > "calendarName": "Founders, Inc. Events", > "guestCount": 399, > "isFree": true, > "isSoldOut": false, > "spotsRemaining": 51, > "needsApproval": true, > "hasWaitlist": false, > "categories": [ > "AI" > ], > "ticketTypes": [ > { > "name": "Builder", > "price": null, > "currency": null, > "needsApproval": true > } > ] > } > ``` # Real estate Source: https://docs.stophy.dev/sources/real-estate Search homes for sale, for rent and sold on Zillow and Realtor.com, and get the price, photos and details for any listing as JSON. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.zillow.com/homes/San-Francisco,-CA_rb/","formats":[{"type":"json","parser":"zillow-search"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.zillow.com/homes/San-Francisco,-CA_rb/", formats: [{ type: "json", parser: "zillow-search" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.zillow.com/homes/San-Francisco,-CA_rb/", "formats": [{"type": "json", "parser": "zillow-search"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "zillow-search", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`zillow-search`](#zillow-search) | A Zillow search page for a place, like zillow\.com/homes/San-Francisco,-CA\_rb/. | 2 credits per call. | | [`zillow-property`](#zillow-property) | A Zillow home page, like zillow\.com/homedetails/.../123\_zpid/. | 1 credit per call. | | [`realtor-search`](#realtor-search) | A Realtor.com search page for a place, like realtor.com/realestateandhomes-search/Austin\_TX. | 1 credit per call. | | [`realtor-property`](#realtor-property) | A Realtor.com home page, like realtor.com/realestateandhomes-detail/... | 1 credit per call. | ## zillow-search A Zillow search page for a place, like zillow\.com/homes/San-Francisco,-CA\_rb/. * **Example page:** [https://www.zillow.com/homes/San-Francisco,-CA\_rb/](https://www.zillow.com/homes/San-Francisco,-CA_rb/) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `status`, `minPrice`, `maxPrice`, `minBedrooms`, `maxBedrooms`, `minBathrooms`, `minSqft`, `maxSqft`, `minLotSize` (Zillow's own Lot size minimum, in square feet), `maxLotSize` (Zillow's own Lot size maximum, in square feet), `minYearBuilt` (Zillow's own Year built minimum), `maxYearBuilt` (Zillow's own Year built maximum), `maxHoa` (Zillow's own Max HOA: the highest monthly HOA fee in USD. 0 means no HOA fee), `minParkingSpots` (Zillow's own Parking spots filter: at least this many (1 to 4)), `daysOnZillow` (Zillow's own Days on Zillow filter: listed in the last 1, 7, 14, 30 or 90 days, or 6, 12, 24 or 36 months. For sold homes it means sold in the last N), `hasPool` (Zillow's own "Must have pool" filter. Only matching homes when true), `hasGarage` (Zillow's own "Must have garage" filter. Only matching homes when true), `hasAirConditioning` (Zillow's own "Must have A/C" filter. Only matching homes when true), `isWaterfront` (Zillow's own "Waterfront" filter. Only matching homes when true), `singleStory` (Zillow's own "Single-story only" filter. Only matching homes when true), `openHouse` (Zillow's own "Must have open house" filter. Only matching homes when true), `priceReduced` (Zillow's own "Must have price reduction" filter. Only matching homes when true), `has3dTour` (Zillow's own "Must have 3D Tour" filter. Only matching homes when true), `petsAllowed` (Zillow's own "Pets Allowed" filter. Only matching homes when true. Rentals only: needs status forRent), `homeTypes` (Zillow's own Home type filter. On rentals, apartment and condo are one Zillow category (apartments, condos and co-ops), so either one returns both), `sort` (Zillow's own sort. priceHigh, bedrooms, bathrooms, squareFeet and lotSize put the largest first, and priceLow the smallest. A rental building sits where its highest unit rent falls), `keywords` (Words the listing must mention, like "pool" or "fixer upper"), `page` (Page number, starting at 1). * **Price:** 2 credits per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "15088840", > "url": "https://www.zillow.com/homedetails/157-28th-Ave-San-Francisco-CA-94121/15088840_zpid/", > "title": "157 28th Ave, San Francisco, CA 94121", > "description": null, > "price": { > "amount": 10000000, > "currency": "USD" > }, > "pricePeriod": "sale", > "status": "forSale", > "address": "157 28th Ave, San Francisco, CA 94121", > "location": { > "latitude": 37.785973, > "longitude": -122.48865 > }, > "bedrooms": 5, > "bathrooms": 7, > "area": { > "amount": 6844, > "unit": "sqft" > }, > "propertyType": "SINGLE_FAMILY", > "rating": null, > "reviewCount": null, > "images": [ > "https://photos.zillowstatic.com/fp/562cd6643e9850b83ae5166c89acb7f6-p_e.jpg" > ], > "host": null, > "statusText": "House for sale", > "addressStreet": "157 28th Ave", > "addressCity": "San Francisco", > "addressRegion": "CA", > "addressPostalCode": "94121", > "daysOnZillow": 5, > "lastSoldAt": null, > "zestimate": 10400300, > "rentZestimate": null, > "brokerName": "Golden Gate Sotheby's Internat", > "buildingName": null, > "buildingMinRent": null, > "buildingMaxRent": null, > "buildingAvailableUnits": null, > "units": [] > } > ], > "cursor": null, > "page": 1, > "total": 981, > "totalPages": 20 > } > ``` ## zillow-property A Zillow home page, like zillow\.com/homedetails/.../123\_zpid/. * **Example page:** [https://www.zillow.com/homedetails/157-28th-Ave-San-Francisco-CA-94121/15088840\_zpid/](https://www.zillow.com/homedetails/157-28th-Ave-San-Francisco-CA-94121/15088840_zpid/) * **Returns:** One listing: `id`, `url`, `title`, `description`, `price`, `pricePeriod`, `status`, `address`, `location`, `bedrooms`, `bathrooms`, `area`, `propertyType`, `rating`, `reviewCount`, `images`, `host`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "15088840", > "url": "https://www.zillow.com/homedetails/157-28th-Ave-San-Francisco-CA-94121/15088840_zpid/", > "title": "157 28th Ave, San Francisco, CA 94121", > "description": "Set on an unusually wide lot in coveted Sea Cliff, 157 28th Avenue is a fully detached contemporary residence offering…", > "price": { > "amount": 10000000, > "currency": "USD" > }, > "pricePeriod": "sale", > "status": "forSale", > "address": "157 28th Ave, San Francisco, CA 94121", > "location": { > "latitude": 37.785973, > "longitude": -122.48865 > }, > "bedrooms": 5, > "bathrooms": 7, > "area": { > "amount": 6844, > "unit": "sqft" > }, > "propertyType": "SINGLE_FAMILY", > "rating": null, > "reviewCount": null, > "images": [ > "https://photos.zillowstatic.com/fp/562cd6643e9850b83ae5166c89acb7f6-cc_ft_1536.jpg", > "https://photos.zillowstatic.com/fp/910c2dcd749cf7fecfee767e8629024d-cc_ft_1536.jpg", > "https://photos.zillowstatic.com/fp/eab5104a6ea4b9b8ef4cea4d2e2e2673-cc_ft_1536.jpg" > ], > "host": null, > "zestimate": 10400300, > "rentZestimate": null, > "lastSoldPrice": 7200000, > "lastSoldAt": "2020-09-22T00:00:00.000Z", > "addressStreet": "157 28th Ave", > "addressCity": "San Francisco", > "addressRegion": "CA", > "addressPostalCode": "94121", > "lotSize": 5418.864, > "lotSizeUnit": "Square Feet", > "yearBuilt": 1923, > "priceHistory": [ > { > "eventDate": "2026-10-31", > "price": 10000000, > "event": "Listed for sale" > } > ], > "daysOnZillow": 5, > "views": null, > "saves": null, > "monthlyHoa": null, > "propertyTaxRate": 1.17, > "mlsId": "426173818", > "mlsName": "SFAR", > "brokerName": "Golden Gate Sotheby's Internat", > "brokerPhone": "+1 555 0100", > "agentName": "Susan Hewitt C.J. Nakagawa", > "agentPhone": "+1 555 0100", > "agentEmail": null, > "facts": [ > { > "name": "bedrooms", > "value": "5" > } > ], > "statusText": "FOR_SALE" > } > ``` ## realtor-search A Realtor.com search page for a place, like realtor.com/realestateandhomes-search/Austin\_TX. * **Example page:** [https://www.realtor.com/realestateandhomes-search/Austin\_TX](https://www.realtor.com/realestateandhomes-search/Austin_TX) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `status`, `minPrice` (Lowest price in US dollars), `maxPrice` (Highest price in US dollars), `minBedrooms`, `maxBedrooms`, `minBathrooms`, `minSqft`, `maxSqft`, `homeTypes`, `sort` (Realtor.com's own order by default. priceLow and priceHigh also order each page by price. On sold homes, newest, price filters and price sorts use the sale), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "8395932351", > "url": "https://www.realtor.com/realestateandhomes-detail/6700-Tulloch-Way_Austin_TX_78754_M83959-32351", > "title": "6700 Tulloch Way, Austin, TX 78754", > "description": null, > "price": { > "amount": 439999, > "currency": "USD" > }, > "pricePeriod": "sale", > "status": "forSale", > "address": "6700 Tulloch Way, Austin, TX 78754", > "location": { > "latitude": 30.354294, > "longitude": -97.61154 > }, > "bedrooms": 4, > "bathrooms": 4, > "area": { > "amount": 3840, > "unit": "sqft" > }, > "propertyType": "single_family", > "rating": null, > "reviewCount": null, > "images": [ > "https://ap.rdcpix.com/e8cfb6fa65df9ca9d347ebd47586e33fl-m3060197626s.jpg" > ], > "host": null, > "isPending": true, > "priceMax": null, > "addressStreet": "6700 Tulloch Way", > "addressCity": "Austin", > "addressRegion": "TX", > "addressPostalCode": "78754", > "bedroomsMax": null, > "lotSqft": 8350, > "yearBuilt": 2005, > "monthlyHoa": 41, > "lastSoldPrice": null, > "publishedAt": "2026-10-02T00:00:00.000Z", > "lastSoldAt": "2005-08-30T00:00:00.000Z" > } > ], > "cursor": null, > "page": null, > "total": 6453 > } > ``` ## realtor-property A Realtor.com home page, like realtor.com/realestateandhomes-detail/... * **Example page:** [https://www.realtor.com/realestateandhomes-detail/581-Leaning-Rock-Rdg\_Austin\_TX\_78737\_M99162-05223](https://www.realtor.com/realestateandhomes-detail/581-Leaning-Rock-Rdg_Austin_TX_78737_M99162-05223) * **Returns:** One listing: `id`, `url`, `title`, `description`, `price`, `pricePeriod`, `status`, `address`, `location`, `bedrooms`, `bathrooms`, `area`, `propertyType`, `rating`, `reviewCount`, `images`, `host`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "9916205223", > "url": "https://www.realtor.com/realestateandhomes-detail/581-Leaning-Rock-Rdg_Austin_TX_78737_M99162-05223", > "title": "581 Leaning Rock Rdg, Austin, TX 78737", > "description": "Step off the front porch into the extended entryway with a 12-foot rotunda ceiling. Off of the main hallway are two…", > "price": { > "amount": 1099900, > "currency": "USD" > }, > "pricePeriod": "sale", > "status": "forSale", > "address": "581 Leaning Rock Rdg, Austin, TX 78737", > "location": { > "latitude": 30.161156, > "longitude": -97.98212 > }, > "bedrooms": 4, > "bathrooms": 5, > "area": { > "amount": 3080, > "unit": "sqft" > }, > "propertyType": "single_family", > "rating": null, > "reviewCount": null, > "images": [ > "https://nh.rdcpix.com/2337494e09a52d8226512341c4506aebl-f2640517s.jpg", > "https://nh.rdcpix.com/2337494e09a52d8226512341c4506aebf-f3605729761s.jpg" > ], > "host": null, > "isPending": false, > "priceMax": null, > "addressStreet": "581 Leaning Rock Rdg", > "addressCity": "Austin", > "addressRegion": "TX", > "addressPostalCode": "78737", > "bedroomsMax": null, > "lotSqft": null, > "yearBuilt": null, > "monthlyHoa": null, > "lastSoldPrice": null, > "garageSpaces": 3, > "stories": 1, > "agentName": null, > "agentEmail": null, > "agentPhone": null, > "brokerName": null, > "priceHistory": [ > { > "date": "2026-10-30", > "event": "Price Changed", > "price": 1099900 > } > ], > "taxHistory": [], > "schools": [ > { > "name": "Sycamore Springs Elementary School", > "rating": 8, > "levels": [ > "elementary" > ], > "fundingType": "public", > "distanceMiles": 1.6 > } > ], > "publishedAt": "2026-10-26T00:00:00.000Z", > "lastSoldAt": null > } > ``` # Shopping Source: https://docs.stophy.dev/sources/shopping Search Amazon products, reviews and best sellers, and TikTok Shop. Search eBay, Craigslist and Facebook Marketplace, and read Trustpilot reviews. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.amazon.com/s?k=laptop&low-price=300&high-price=900&s=review-rank","formats":[{"type":"json","parser":"amazon-search"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.amazon.com/s?k=laptop&low-price=300&high-price=900&s=review-rank", formats: [{ type: "json", parser: "amazon-search" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.amazon.com/s?k=laptop&low-price=300&high-price=900&s=review-rank", "formats": [{"type": "json", "parser": "amazon-search"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "amazon-search", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`amazon-search`](#amazon-search) | An Amazon search page with a search word or a department, like amazon.com/s?k=laptop. | 1 credit per call. | | [`amazon-product`](#amazon-product) | An Amazon product page, like amazon.com/dp/``. | 1 credit per call. | | [`amazon-reviews`](#amazon-reviews) | An Amazon product page. | 1 credit per call. | | [`amazon-bestsellers`](#amazon-bestsellers) | An Amazon Best Sellers category page, like amazon.com/Best-Sellers-Electronics/zgbs/electronics. | 1 credit per call. | | [`tiktok-shop`](#tiktok-shop) | A TikTok Shop search page (/k/), store page (/store/) or product page (/pdp/). | 1 credit per call. | | [`ebay-search`](#ebay-search) | An ebay.com search page, like ebay.com/sch/i.html?\_nkw=iphone. | 1 credit per call. | | [`ebay-item`](#ebay-item) | An eBay item page, like ebay.com/itm/``. | 1 credit per call. | | [`facebook-marketplace`](#facebook-marketplace) | A Facebook Marketplace search page with a city and a query, like facebook.com/marketplace/austin/search?query=bike. | 1 credit per call. | | [`craigslist-search`](#craigslist-search) | A Craigslist search page with a five-digit US ZIP code in postal, like sfbay.craigslist.org/search/sss?query=bike\&postal=94103. | 1 credit per 10 listings. | | [`trustpilot-search`](#trustpilot-search) | A Trustpilot search page, like trustpilot.com/search?query=stripe. | 1 credit per call. | | [`trustpilot-company`](#trustpilot-company) | A Trustpilot company page, like trustpilot.com/review/stripe.com. | 1 credit per call. | | [`trustpilot-reviews`](#trustpilot-reviews) | A Trustpilot company page, like trustpilot.com/review/stripe.com. | 1 credit per call. | ## amazon-search An Amazon search page with a search word or a department, like amazon.com/s?k=laptop. * **Example page:** [https://www.amazon.com/s?k=laptop\&low-price=300\&high-price=900\&s=review-rank](https://www.amazon.com/s?k=laptop\&low-price=300\&high-price=900\&s=review-rank) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `category`, `minRating`, `brand`, `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "B0HGMH4B7S", > "url": "https://www.amazon.com/dp/B0HGMH4B7S", > "title": "HP 14 inch Laptop, Intel Processor N150, 4GB RAM 384GB Storage(UFS+SD Card)", > "brand": null, > "description": null, > "price": { > "amount": 319, > "currency": "USD" > }, > "originalPrice": null, > "rating": 5, > "reviewCount": 54, > "availability": null, > "images": [ > "https://m.media-amazon.com/images/I/71uaMcxitqL._AC_UY218_.jpg" > ], > "categories": [], > "seller": null, > "boughtPastMonth": 200, > "isSponsored": false > } > ], > "cursor": null, > "page": 1, > "total": 18815 > } > ``` ## amazon-product An Amazon product page, like amazon.com/dp/``. * **Example page:** [https://www.amazon.com/dp/B0CX23V2ZK](https://www.amazon.com/dp/B0CX23V2ZK) * **Returns:** One product: `id`, `url`, `title`, `brand`, `description`, `price`, `originalPrice`, `rating`, `reviewCount`, `availability`, `images`, `categories`, `seller`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "B0CX23V2ZK", > "url": "https://www.amazon.com/dp/B0CX23V2ZK", > "title": "Apple 2024 MacBook Air 13-inch Laptop with M3 chip: Built for Apple Intelligence, 13.6-inch Liquid Retina Display, 8GB…", > "brand": "Apple", > "description": null, > "price": null, > "originalPrice": null, > "rating": 4.8, > "reviewCount": 1081, > "availability": "Currently unavailable.", > "images": [ > "https://m.media-amazon.com/images/I/71-D1xCuVwL._AC_SL1500_.jpg", > "https://m.media-amazon.com/images/I/61LbQpnFNvL._AC_SL1500_.jpg", > "https://m.media-amazon.com/images/I/61S2t5yhVSL._AC_SL1500_.jpg" > ], > "categories": [], > "seller": null, > "bullets": [ > "LEAN. MEAN. M3 MACHINE - With a powerful 8-core CPU and 10-core GPU, the blazing-fast MacBook Air with M3 chip is a…", > "BUILT FOR APPLE INTELLIGENCE-Apple Intelligence is the personal intelligence system that helps you write, express…", > "PORTABLE DESIGN - Lightweight and under half an inch thin, so you can take MacBook Air anywhere you go." > ], > "variants": [], > "sellerShipsFrom": null, > "bestSellersRank": [], > "specs": [ > { > "name": "Brand", > "value": "Apple" > } > ], > "topReviews": [] > } > ``` ## amazon-reviews An Amazon product page. Marketplaces outside the US, like amazon.in/dp/``, show their top reviews without sign-in, up to 13 for the product page. Amazon US shows reviews only after sign-in, so an amazon.com page returns reviews for few products. * **Example page:** [https://www.amazon.in/dp/B0CHX1W1XY](https://www.amazon.in/dp/B0CHX1W1XY) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `rating` (Only reviews with this star rating), `verifiedOnly` (Only reviews from verified purchases), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "R3CGMF6T85GZEN", > "url": null, > "author": { > "id": null, > "name": "Kaleem", > "handle": null, > "url": null, > "avatarUrl": null > }, > "rating": 5, > "title": "Great performance", > "text": "I’m really happy with this phone. The performance is smooth, and the display quality is impressive.", > "publishedAt": "2026-10-30T00:00:00.000Z", > "likes": 0, > "response": null, > "subject": { > "id": "B0CHX1W1XY", > "name": null, > "url": null > }, > "isVerified": true, > "variant": null, > "imageUrls": [] > } > ], > "cursor": null, > "page": null, > "total": null > } > ``` ## amazon-bestsellers An Amazon Best Sellers category page, like amazon.com/Best-Sellers-Electronics/zgbs/electronics. * **Example page:** [https://www.amazon.com/Best-Sellers-Electronics/zgbs/electronics](https://www.amazon.com/Best-Sellers-Electronics/zgbs/electronics) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "B08JHCVHTY", > "url": "https://www.amazon.com/dp/B08JHCVHTY", > "title": "blink plus plan with monthly auto-renewal", > "brand": null, > "description": null, > "price": { > "amount": 11.99, > "currency": "USD" > }, > "originalPrice": null, > "rating": 4.4, > "reviewCount": 281734, > "availability": null, > "images": [ > "https://images-na.ssl-images-amazon.com/images/I/31YHGbJsldL._AC_UL300_SR300,200_.png" > ], > "categories": [], > "seller": null, > "rank": 1 > } > ], > "cursor": null, > "page": 1, > "total": null, > "category": "Electronics" > } > ``` ## tiktok-shop A TikTok Shop search page (/k/), store page (/store/) or product page (/pdp/). Send options view reviews on a product page for its reviews. * **Example page:** [https://shop.tiktok.com/us/k/gummies](https://shop.tiktok.com/us/k/gummies) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "1729432589178278226", > "url": "https://shop.tiktok.com/us/pdp/gummies-combo-pack-by-bearvana-womens-fitness-aid-with-herbs/1729432589178278226", > "title": "BEARVANA Women's 16-Herb Wellness Gummies Combo Pack | Vitamins A C E and B6 | Daily Gummies Worth the Hype | Berry…", > "brand": null, > "description": null, > "price": { > "amount": 59.99, > "currency": "USD" > }, > "originalPrice": null, > "rating": 4.5, > "reviewCount": 39182, > "availability": null, > "images": [ > "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/f77b653568a4438680b65f19bd753731~tplv-fhlh96ny…" > ], > "categories": [], > "seller": { > "id": "7495523339641194834", > "name": "BEARVANA", > "handle": null, > "url": null, > "avatarUrl": null > }, > "sold": 404309 > } > ], > "cursor": "30::1729432589178278226,1732759068244480363,1732805322000928869,1732766556619117362,1729890372836496007,1730206447762903669,1732757985036964658,1731659207048...", > "page": null, > "total": null > } > ``` ## ebay-search An ebay.com search page, like ebay.com/sch/i.html?\_nkw=iphone. * **Example page:** [https://www.ebay.com/sch/i.html?\_nkw=iphone+15&\_udlo=300&\_udhi=800&\_sop=15](https://www.ebay.com/sch/i.html?_nkw=iphone+15&_udlo=300&_udhi=800&_sop=15) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `condition`, `auctionsOnly` (Only auctions. With sort endingSoonest this lists auctions about to end; ebay.item then returns what each one sold for), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "168683336290", > "url": "https://www.ebay.com/itm/168683336290", > "title": "Apple iPhone 15 128GB (BLACK)", > "brand": null, > "description": null, > "price": { > "amount": 300, > "currency": "USD" > }, > "originalPrice": null, > "rating": null, > "reviewCount": null, > "availability": null, > "images": [ > "https://i.ebayimg.com/images/g/GhMAAeSwWxpqpV1Z/s-l500.jpg" > ], > "categories": [], > "seller": { > "id": null, > "name": "brittanhick166", > "handle": null, > "url": null, > "avatarUrl": null > }, > "priceMax": null, > "isPriceHidden": false, > "shippingCost": null, > "isPickupOnly": true, > "totalPrice": { > "amount": 300, > "currency": "USD" > }, > "condition": "Pre-Owned", > "isAuction": false, > "bids": null, > "timeLeft": null, > "hasBestOffer": true, > "itemLocation": "United States", > "quantitySold": null, > "watchers": 70, > "sellerFeedbackPercent": null, > "sellerFeedbackScore": 0 > } > ], > "cursor": null, > "page": 1, > "total": 4800 > } > ``` ## ebay-item An eBay item page, like ebay.com/itm/``. * **Example page:** [https://www.ebay.com/itm/266625967665](https://www.ebay.com/itm/266625967665) * **Returns:** One product: `id`, `url`, `title`, `brand`, `description`, `price`, `originalPrice`, `rating`, `reviewCount`, `availability`, `images`, `categories`, `seller`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "266625967665", > "url": "https://www.ebay.com/itm/266625967665", > "title": "Nintendo Switch 64GB OLED White Console 1 Day Ship Excellent Refurbished", > "brand": "Nintendo", > "description": "?? For U.S. Buyers:\n\nNo import duties will be charged. You can purchase with peace of mind.\n\n? For Buyers Outside the…", > "price": { > "amount": 296, > "currency": "USD" > }, > "originalPrice": { > "amount": 370, > "currency": "USD" > }, > "rating": null, > "reviewCount": null, > "availability": "available", > "images": [ > "https://i.ebayimg.com/images/g/O14AAOSwOz9mVJtw/s-l1600.png", > "https://i.ebayimg.com/images/g/c~YAAOSwI71lqz3d/s-l1600.jpg", > "https://i.ebayimg.com/images/g/7awAAOSwfV1lqon7/s-l1600.jpg" > ], > "categories": [ > "Electronics", > "Video Games & Consoles", > "Video Game Consoles" > ], > "seller": { > "id": null, > "name": "Samurai_Game.Shop", > "handle": null, > "url": null, > "avatarUrl": null > }, > "model": "Nintendo Switch (OLED Model)", > "specifics": [ > { > "name": "Seller Notes", > "value": "“Excellent - Refurbished: The item is in like-new condition, backed by a one year warranty. It has been professionally…" > } > ], > "condition": "Excellent - Refurbished", > "isAuction": false, > "bids": null, > "isEnded": false, > "endedAt": null, > "isSold": false, > "soldPrice": null, > "soldAt": null, > "isAvailable": true, > "quantityAvailable": 5, > "quantitySold": 160, > "sellerFeedbackScore": 9472, > "sellerFeedbackPercent": 99.9, > "shippingCost": { > "amount": 0, > "currency": "USD" > }, > "shippingPostalCode": "08232", > "itemLocation": "Gifu, Japan", > "returnsAccepted": true, > "returnDays": 30, > "listedAt": "2024-01-20T03:27:03.000Z" > } > ``` ## facebook-marketplace A Facebook Marketplace search page with a city and a query, like facebook.com/marketplace/austin/search?query=bike. * **Example page:** [https://www.facebook.com/marketplace/austin/search?query=bike](https://www.facebook.com/marketplace/austin/search?query=bike) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `minPrice` (Lowest price in local currency (e.g., 50)), `maxPrice` (Highest price in local currency (e.g., 500)), `sort` (Sort order (newest, priceLow or priceHigh), relevance by default). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "4592280847709289", > "url": "https://www.facebook.com/marketplace/item/4592280847709289/", > "title": "Bike", > "description": null, > "price": { > "amount": 85, > "currency": "USD" > }, > "pricePeriod": "sale", > "status": "available", > "address": "Austin, TX", > "location": null, > "bedrooms": null, > "bathrooms": null, > "area": null, > "propertyType": null, > "rating": null, > "reviewCount": null, > "images": [ > "https://scontent-iad3-2.xx.fbcdn.net/v/t39.84726-6/886726471_1489389276412115_3383755310775348626_n.jpg?stp=c0.43.261.2…" > ], > "host": null, > "priceText": "$85", > "city": "Austin", > "state": "TX", > "publishedAt": "2026-11-04T00:16:04.000Z", > "isPending": false > } > ], > "cursor": null, > "page": null, > "total": null, > "location": "Austin, Texas", > "latitude": 30.2677, > "longitude": -97.7475 > } > ``` ## craigslist-search A Craigslist search page with a five-digit US ZIP code in postal, like sfbay.craigslist.org/search/sss?query=bike\&postal=94103. * **Example page:** [https://sfbay.craigslist.org/search/sss?query=bike\&postal=94103\&search\_distance=25](https://sfbay.craigslist.org/search/sss?query=bike\&postal=94103\&search_distance=25) * **Returns:** A list of listings: `results`, `cursor`, `page`, `total`. * **Options:** `minPrice` (Lowest price in US dollars (e.g., 50)), `maxPrice` (Highest price in US dollars (e.g., 500)), `limit` (Return at most this many listings. You pay 1 credit per 10 returned). * **Price:** 1 credit per 10 listings. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7995382659", > "url": "https://www.craigslist.org/view/d/san-francisco-2013-bmw-k1600/9GFQHZkctQ4nJBUeAfZHQh", > "title": "2013 BMW K1600", > "description": null, > "price": { > "amount": 6500, > "currency": "USD" > }, > "pricePeriod": null, > "status": null, > "address": "noe valley", > "location": { > "latitude": 37.745, > "longitude": -122.4383 > }, > "bedrooms": null, > "bathrooms": null, > "area": null, > "propertyType": null, > "rating": null, > "reviewCount": null, > "images": [ > "https://images.craigslist.org/01212_dEwA5HIEfjT_1320MM_600x450.jpg" > ], > "host": null, > "publishedAt": "2026-11-04T23:12:28.000Z" > } > ], > "cursor": null, > "page": null, > "total": 5031 > } > ``` ## trustpilot-search A Trustpilot search page, like trustpilot.com/search?query=stripe. * **Example page:** [https://www.trustpilot.com/search?query=payments](https://www.trustpilot.com/search?query=payments) * **Returns:** A list of products: `results`, `cursor`, `page`, `total`. * **Options:** `page` (Page number, starting at 1. Trustpilot shows 10 pages of 10 companies without an account, so one search reaches at most 100 companies even when total is larger. Make the query more specific to reach the rest). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "50489e6800006400051ae0d6", > "url": "https://www.trustpilot.com/review/stripe.com", > "title": "https://stripe.com/payments/checkout", > "brand": null, > "description": null, > "price": null, > "originalPrice": null, > "rating": 1.6, > "reviewCount": 17569, > "availability": null, > "images": [], > "categories": [ > "Payment Service" > ], > "seller": null, > "companyDomain": "stripe.com", > "website": "https://stripe.com", > "stars": 1.5, > "addressStreet": "510 Townsend Street", > "addressCity": "San Francisco", > "addressPostalCode": "94103", > "addressCountry": "United States" > } > ], > "cursor": null, > "page": 1, > "total": 273 > } > ``` ## trustpilot-company A Trustpilot company page, like trustpilot.com/review/stripe.com. * **Example page:** [https://www.trustpilot.com/review/stripe.com](https://www.trustpilot.com/review/stripe.com) * **Returns:** One product: `id`, `url`, `title`, `brand`, `description`, `price`, `originalPrice`, `rating`, `reviewCount`, `availability`, `images`, `categories`, `seller`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "50489e6800006400051ae0d6", > "url": "https://www.trustpilot.com/review/stripe.com", > "title": "https://stripe.com/payments/checkout", > "brand": null, > "description": "Millions of businesses of all sizes-from startups to large enterprises-use Stripe’s software and APIs to accept…", > "price": null, > "originalPrice": null, > "rating": 1.6, > "reviewCount": 17568, > "availability": null, > "images": [], > "categories": [ > "Payment Service" > ], > "seller": null, > "companyDomain": "stripe.com", > "website": "https://stripe.com", > "stars": 1.5, > "addressStreet": "510 Townsend Street", > "addressCity": "San Francisco", > "addressPostalCode": "94103", > "addressCountry": "United States", > "ratingsOne": 9141, > "ratingsTwo": 513, > "ratingsThree": 468, > "ratingsFour": 725, > "ratingsFive": 6721, > "isClaimed": true, > "isClosed": false, > "email": "https://support.stripe.com/contact", > "phone": null, > "negativeReviewsRepliedPercent": 100, > "averageDaysToReply": 1.6 > } > ``` ## trustpilot-reviews A Trustpilot company page, like trustpilot.com/review/stripe.com. * **Example page:** [https://www.trustpilot.com/review/stripe.com?stars=1\&stars=2\&languages=en](https://www.trustpilot.com/review/stripe.com?stars=1\&stars=2\&languages=en) * **Returns:** A list of reviews: `results`, `cursor`, `page`, `total`. * **Options:** `datePublished` (Only reviews published in the last 30 days, 3, 6 or 12 months), `verifiedOnly` (Only reviews Trustpilot marks as verified), `search` (Only reviews that mention this word or phrase), `page` (Page number, starting at 1. Trustpilot shows 10 pages of 20 reviews without an account; narrow with ratings, language, datePublished or search to reach older reviews). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "6aeb69e52f5f72549e50ecc2", > "url": "https://www.trustpilot.com/reviews/6aeb69e52f5f72549e50ecc2", > "author": { > "id": null, > "name": "Bystrík Královič", > "handle": null, > "url": null, > "avatarUrl": null > }, > "rating": 1, > "title": "Automatically created Stripe Link account storing personal and payment information", > "text": "I made a one time payment on a website that uses Stripe, and during the checkout process, I was apparently signed up…", > "publishedAt": "2026-11-04T19:22:45.000Z", > "likes": null, > "response": null, > "subject": { > "id": "stripe.com", > "name": "https://stripe.com/payments/checkout", > "url": "https://www.trustpilot.com/review/stripe.com" > }, > "language": "en", > "experiencedDate": "2026-11-04T00:00:00.000Z", > "isVerified": false, > "authorCountry": "SK" > } > ], > "cursor": null, > "page": 1, > "total": 7505 > } > ``` # Social Source: https://docs.stophy.dev/sources/social Search and read posts, profiles and comments on Reddit, Instagram, LinkedIn, Pinterest, Facebook, X and Threads, and get them back as JSON. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.reddit.com/search/?q=web+scraping&sort=top&t=year","formats":[{"type":"json","parser":"reddit-search"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.reddit.com/search/?q=web+scraping&sort=top&t=year", formats: [{ type: "json", parser: "reddit-search" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.reddit.com/search/?q=web+scraping&sort=top&t=year", "formats": [{"type": "json", "parser": "reddit-search"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "reddit-search", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`reddit-search`](#reddit-search) | A Reddit search page with a q query, on reddit.com/search or inside a subreddit. | 1 credit per call. | | [`reddit-post`](#reddit-post) | A Reddit post page or a redd.it short link. | 1 credit per 200 comments. | | [`reddit-subreddit`](#reddit-subreddit) | A subreddit page, like reddit.com/r/programming/ or reddit.com/r/programming/top/?t=week. | 1 credit per call. | | [`reddit-user`](#reddit-user) | A Reddit user page, like reddit.com/user/spez or reddit.com/user/spez/comments. | 1 credit per call. | | [`reddit-subreddits`](#reddit-subreddits) | The Reddit list of popular subreddits, reddit.com/subreddits. | 1 credit per call. | | [`instagram-post`](#instagram-post) | An Instagram post, reel or share link. | 1 credit per call. | | [`instagram-profile`](#instagram-profile) | An Instagram profile page, like instagram.com/natgeo. | 1 credit per call. | | [`instagram-comments`](#instagram-comments) | An Instagram post, reel or share link. | 1 credit per call. | | [`instagram-feed`](#instagram-feed) | An Instagram hashtag, location or keyword search page, like instagram.com/explore/tags/travel. | 1 credit per call. | | [`x-profile`](#x-profile) | An X profile page, like x.com/nasa. | 1 credit per call. | | [`x-post`](#x-post) | An X post page, like x.com/nasa/status/``. | 1 credit per call. | | [`threads-profile`](#threads-profile) | A Threads profile page, like threads.com/@nasa. | 1 credit per call. | | [`threads-post`](#threads-post) | A Threads post page, like threads.com/@nasa/post/``. | 1 credit per call. | | [`pinterest-search`](#pinterest-search) | A Pinterest pin or video search page with a q query, like pinterest.com/search/pins/?q=kitchen. | 1 credit per call. | | [`pinterest-pin`](#pinterest-pin) | A Pinterest pin page or a pin.it short link. | 1 credit per call. | | [`pinterest-board`](#pinterest-board) | A Pinterest board page, like pinterest.com/``/``/. | 1 credit per call. | | [`pinterest-profile`](#pinterest-profile) | A Pinterest profile page, like pinterest.com/marthastewart/. | 1 credit per call. | | [`facebook-page`](#facebook-page) | A Facebook page, like facebook.com/NASA. | 1 credit per call. | | [`facebook-post`](#facebook-post) | A Facebook post, reel or video page, or an fb.watch link. | 1 credit per call. | | [`facebook-comments`](#facebook-comments) | A Facebook post, reel or video page, or an fb.watch link. | 1 credit per call. | | [`linkedin-company`](#linkedin-company) | A LinkedIn company page. | 1 credit per call. | | [`linkedin-profile`](#linkedin-profile) | A LinkedIn profile page. | 1 credit per call. | | [`linkedin-posts`](#linkedin-posts) | A LinkedIn profile or company page. | 1 credit per call. | ## reddit-search A Reddit search page with a q query, on reddit.com/search or inside a subreddit. Add type=sr to the page for communities or type=user for people. * **Example page:** [https://www.reddit.com/search/?q=web+scraping\&sort=top\&t=year](https://www.reddit.com/search/?q=web+scraping\&sort=top\&t=year) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `subreddit`, `cursor` (The cursor from the previous response. Send it as is), `query` (Words to find. With any sort other than relevance, a query of several words matches that exact phrase; use sort relevance to match the words anywhere in a post. Quotes, AND, OR, NOT, title:, selftext:, author:, subreddit: and site: are used as typed), `type`, `sort` (relevance matches the words anywhere in a post. hot, top, newest and mostComments match the exact phrase, so a query of several words only returns posts containing that phrase), `time` (Reddit's own time filter. Leave out for Reddit's default). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "1vmwcb7", > "url": "https://www.reddit.com/r/InterstellarKinetics/comments/1vmwcb7/breaking_trump_is_being_sued_by_the_intercept/", > "title": "BREAKING: Trump Is Being Sued By The Intercept & Freedom Of The Press Foundation Over “Brazen” Scheme Charging Up To…", > "text": "President Trump is being sued by nonprofit news groups The Intercept and the Freedom of the Press Foundation over…", > "author": { > "id": "1a2qoapr8q", > "name": null, > "handle": "Kamoto31", > "url": "https://www.reddit.com/user/Kamoto31/", > "avatarUrl": null, > "isVerified": null > }, > "community": { > "name": "InterstellarKinetics", > "url": "https://www.reddit.com/r/InterstellarKinetics/" > }, > "publishedAt": "2026-08-13T01:02:48.590Z", > "likes": 5481, > "comments": 59, > "shares": null, > "views": null, > "media": [], > "hashtags": [], > "score": 5481, > "upvotePercent": 99.4, > "flair": "FINANCIAL FRONTIERS", > "linkUrl": "https://arstechnica.com/tech-policy/2026/08/trump-sued-over-brazen-scheme-to-sell-truth-social-api-access-for-100k-a-mo…", > "thumbnailUrl": "https://external-preview.redd.it/zQG3SjQ_AvJknEM2xFLmeX-acdp5CN8PUgwKe9A2X5s.jpeg?auto=webp&s=248d4f38ccc72103e0c836158…", > "isNsfw": false, > "isVideo": false, > "isPinned": false, > "videoHlsUrl": null, > "videoDurationSeconds": null, > "pollOptions": [], > "pollTotalVotes": null, > "pollEndsAt": null, > "repostOfUrl": null > } > ], > "cursor": "MjQ=", > "page": null, > "total": null > } > ``` ## reddit-post A Reddit post page or a redd.it short link. Send options view discussions to list the other subreddits where the same link was shared. * **Example page:** [https://www.reddit.com/r/programming/comments/1xjiofl/how\_curl\_was\_accidentally\_turingcomplete\_for\_nine/](https://www.reddit.com/r/programming/comments/1xjiofl/how_curl_was_accidentally_turingcomplete_for_nine/) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Options:** `comment` (A comment id or link: returns that comment's thread, like Reddit's own link), `sort` (Reddit's own comment sort), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per 200 comments. > [accordion] Example response > > ```json theme={null} > { > "id": "1xjiofl", > "url": "https://www.reddit.com/r/programming/comments/1xjiofl/how_curl_was_accidentally_turingcomplete_for_nine/", > "title": "How curl was accidentally Turing-complete for nine months", > "text": null, > "author": { > "id": "8fmwystd", > "name": null, > "handle": "Dull_Replacement8890", > "url": "https://www.reddit.com/user/Dull_Replacement8890/", > "avatarUrl": null, > "isVerified": null > }, > "community": { > "name": "programming", > "url": "https://www.reddit.com/r/programming/" > }, > "publishedAt": "2026-10-30T15:37:35.622Z", > "likes": 758, > "comments": 41, > "shares": null, > "views": null, > "media": [], > "hashtags": [], > "score": 758, > "upvotePercent": 98, > "flair": null, > "linkUrl": "https://seriot.ch/computation/curl.html", > "thumbnailUrl": null, > "isNsfw": false, > "isVideo": false, > "isPinned": false, > "videoHlsUrl": null, > "videoDurationSeconds": null, > "pollOptions": [], > "pollTotalVotes": null, > "pollEndsAt": null, > "repostOfUrl": null, > "commentList": [ > { > "id": "19rvxq0bhfawy", > "url": "https://www.reddit.com/r/programming/comments/1xjiofl/how_curl_was_accidentally_turingcomplete_for_nine/19rvxq0bhfawy/", > "author": { > "id": "4dnn5", > "name": null, > "handle": "tsammons", > "url": "https://www.reddit.com/user/tsammons/", > "avatarUrl": null, > "isVerified": null > }, > "text": "I love how the first paragraph reads like my first recitation in college. Then it dives into discrete math midterm.", > "publishedAt": "2026-10-30T15:45:16.867Z", > "likes": 300, > "replies": null, > "parentId": null, > "score": 300, > "depth": 0, > "isSubmitter": false, > "isPinned": false > } > ], > "cursor": null > } > ``` ## reddit-subreddit A subreddit page, like reddit.com/r/programming/ or reddit.com/r/programming/top/?t=week. * **Example page:** [https://www.reddit.com/r/programming/top/?t=week](https://www.reddit.com/r/programming/top/?t=week) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "1xjiofl", > "url": "https://www.reddit.com/r/programming/comments/1xjiofl/how_curl_was_accidentally_turingcomplete_for_nine/", > "title": "How curl was accidentally Turing-complete for nine months", > "text": null, > "author": { > "id": "8fmwystd", > "name": null, > "handle": "Dull_Replacement8890", > "url": "https://www.reddit.com/user/Dull_Replacement8890/", > "avatarUrl": null, > "isVerified": null > }, > "community": { > "name": "programming", > "url": "https://www.reddit.com/r/programming/" > }, > "publishedAt": "2026-10-30T15:37:35.622Z", > "likes": 758, > "comments": 41, > "shares": null, > "views": null, > "media": [], > "hashtags": [], > "score": 758, > "upvotePercent": 98, > "flair": null, > "linkUrl": "https://seriot.ch/computation/curl.html", > "thumbnailUrl": null, > "isNsfw": false, > "isVideo": false, > "isPinned": false, > "videoHlsUrl": null, > "videoDurationSeconds": null, > "pollOptions": [], > "pollTotalVotes": null, > "pollEndsAt": null, > "repostOfUrl": null > } > ], > "cursor": "dDNfMXhscWZiNg==", > "page": null, > "total": null, > "subreddit": { > "id": "2fwo", > "handle": "programming", > "name": "programming", > "bio": "Computer Programming", > "avatarUrl": "https://styles.redditmedia.com/t5_2fwo/styles/communityIcon_1bqa1ibfp8q11.png?width=64&frame=1&auto=webp&s=2545f3c0332e…", > "isVerified": null, > "followers": 6932223, > "following": null, > "posts": null, > "website": null, > "location": null, > "category": null, > "url": "https://www.reddit.com/r/programming/", > "createdAt": "2006-02-28T18:19:29.538Z", > "isNsfw": false > }, > "sidebar": "/r/programming is a reddit for discussion and news about [computer…", > "rules": [ > { > "title": "No LLM-Written Content", > "description": "If you don't want to write it, we don't want to read it. This includes the use of LLMs for translation or…" > } > ] > } > ``` ## reddit-user A Reddit user page, like reddit.com/user/spez or reddit.com/user/spez/comments. * **Example page:** [https://www.reddit.com/user/spez/](https://www.reddit.com/user/spez/) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `tab`, `sort` (Reddit's own sort), `time` (Reddit's own time filter. Leave out for Reddit's default), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "19ruo33ofgh8i", > "url": "https://www.reddit.com/r/RDDT/comments/1xiupuc/reddit_announces_q326_earnings_plus_ama/19ruo33ofgh8i/", > "title": "Reddit Announces Q3’26 Earnings (plus AMA!)", > "text": "Pretty simple. For people who are already coming to Reddit every week, we have to give them a reason to come back…", > "author": null, > "community": { > "name": "RDDT", > "url": "https://www.reddit.com/r/RDDT/" > }, > "publishedAt": "2026-10-29T22:42:06.463Z", > "likes": 0, > "comments": null, > "shares": null, > "views": null, > "media": [], > "hashtags": [], > "type": "comment", > "score": -8, > "postId": "1xiupuc" > } > ], > "cursor": "overview.eyJwb3N0cyI6ImRETmZNWFpuWW10blpRPT0iLCJjb21tZW50cyI6ImRERmZiM013YW5SME9RPT0ifQ", > "page": null, > "total": null, > "profile": { > "id": "1w72", > "handle": "spez", > "name": null, > "bio": null, > "avatarUrl": "https://styles.redditmedia.com/t5_3k30p/styles/profileIcon_uj015iwx9s7g1.png?frame=1&auto=webp&crop=256%3A256%2Csmart&s…", > "isVerified": null, > "followers": null, > "following": null, > "posts": null, > "website": null, > "location": null, > "category": null, > "url": "https://www.reddit.com/user/spez/", > "karma": 941389, > "createdAt": "2005-06-06T04:00:00.000Z" > } > } > ``` ## reddit-subreddits The Reddit list of popular subreddits, reddit.com/subreddits. * **Example page:** [https://www.reddit.com/subreddits/](https://www.reddit.com/subreddits/) * **Returns:** A list of profiles: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "2r397", > "url": "https://www.reddit.com/r/whatisit/", > "handle": "whatisit", > "name": "What is it?", > "bio": "Do you know what it is? No, we don't either. Maybe someone does?", > "avatarUrl": "https://styles.redditmedia.com/t5_2r397/styles/communityIcon_ds28lp4dy5rg1.png?width=64&frame=1&auto=webp&s=f16ad15c3e6…", > "isVerified": null, > "followers": 2934223, > "following": null, > "posts": null, > "website": null, > "location": null, > "category": null, > "createdAt": "2009-07-26T18:12:48.273Z", > "isNsfw": false > } > ], > "cursor": "seen_a48c4e57-63d0-431a-b5b2-293480ee6320", > "page": null, > "total": null > } > ``` ## instagram-post An Instagram post, reel or share link. * **Example page:** [https://www.instagram.com/p/DeuOR-CjKE9/](https://www.instagram.com/p/DeuOR-CjKE9/) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "4012207125530714429", > "url": "https://www.instagram.com/p/DeuOR-CjKE9/", > "title": null, > "text": "Some of the best reasons to travel in 2027 are far from the usual destinations. 🌎\n\nNational Geographic’s picks for…", > "author": { > "id": "787132", > "name": "National Geographic", > "handle": "natgeo", > "url": "https://www.instagram.com/natgeo/", > "avatarUrl": "https://scontent-dfw6-2.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-j…", > "isVerified": true > }, > "community": null, > "publishedAt": "2026-10-20T16:06:30.000Z", > "likes": 16397, > "comments": 261, > "shares": null, > "views": null, > "media": [ > { > "type": "image", > "url": "https://scontent-dfw6-2.cdninstagram.com/v/t51.82787-15/858921974_18710195065019133_277441153414192961_n.jpg?stp=dst-jp…" > } > ], > "hashtags": [ > "BestOfTheWorld" > ], > "postCode": "DeuOR-CjKE9", > "type": "photo", > "mentions": [], > "thumbnailUrl": "https://scontent-dfw6-2.cdninstagram.com/v/t51.82787-15/858921974_18710195065019133_277441153414192961_n.jpg?stp=dst-jp…", > "imageDescription": "Photo by National Geographic on October 20, 2026. May be an image of outdoors and text.", > "isPinned": false, > "taggedUsers": [ > "natgeotravel" > ], > "coauthors": [ > "natgeotravel" > ], > "audioTitle": null, > "audioArtist": null, > "audioIsOriginal": null, > "isPaidPartnership": false, > "sponsors": [], > "commentList": [ > { > "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18181102558431616/", > "author": { > "id": "49884965268", > "name": null, > "handle": "querosercomunista", > "url": "https://www.instagram.com/querosercomunista/", > "avatarUrl": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-19/886273225_18099923474661269_8757655740803320523_n.jpg?stp=dst-j…", > "isVerified": false > }, > "text": "#protejamnossospovosindigenas\n#PovosIndígenas #GuaraniKaiowá #protejaospovosindigenas #JustiçaNoCampo #exercitodolula", > "publishedAt": "2026-11-04T21:09:54.000Z", > "likes": 0, > "replies": null, > "parentId": null, > "id": "18181102558431616" > } > ] > } > ``` ## instagram-profile An Instagram profile page, like instagram.com/natgeo. Its reels tab, like instagram.com/natgeo/reels, or options view reels on the profile page, returns the reels. * **Example page:** [https://www.instagram.com/natgeo/](https://www.instagram.com/natgeo/) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "787132", > "url": "https://www.instagram.com/natgeo/", > "handle": "natgeo", > "name": "National Geographic", > "bio": "Step into wonder and find your inner explorer with National Geographic 🌎", > "avatarUrl": "https://scontent-ord5-1.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-j…", > "isVerified": true, > "followers": 268204142, > "following": 195, > "posts": 32145, > "website": "http://visitstore.bio/natgeo", > "location": null, > "category": null, > "bioLinkUrls": [ > "http://visitstore.bio/natgeo", > "https://ngmdomsubs.nationalgeographic.com/servlet/OrdersGateway?cds_mag_code=NGM&cds_page_id=283562&cds_response_key=I5…" > ], > "isPrivate": false, > "postsAnalyzed": 12, > "averageLikes": 96925, > "engagementRate": 0.036, > "recentPosts": [ > { > "title": null, > "text": "Even a moment’s rest on Everest can come with a reminder of just how unpredictable the mountain can be.\n\nFrom…", > "author": { > "id": "787132", > "name": null, > "handle": "natgeo", > "url": null, > "avatarUrl": null, > "isVerified": null > }, > "community": null, > "publishedAt": null, > "likes": 43820, > "comments": null, > "shares": null, > "views": 1603019, > "media": [ > { > "type": "image", > "url": "https://scontent-ord5-1.cdninstagram.com/v/t51.82787-15/865525088_18712762651019133_8954025122327073428_n.jpg?stp=dst-j…" > } > ], > "hashtags": [], > "id": "4017311023166285121", > "url": "https://www.instagram.com/reel/DfAWxdIFmVB/", > "postCode": "DfAWxdIFmVB", > "type": "reel", > "mentions": [ > "chaivasarhelyi", > "jimmychin" > ], > "imageDescription": "Video by National Geographic on October 27, 2026. May be an image of ski, glasses, ski slope and text." > } > ], > "cursor": "AQHTTOsiw50N3nKKxR7N1fBjuEgnYZtTvRckOd9DaURJrqMPxNIgNrqqH91cbjGodC4KrMz-buKnudn41Gu_K_5fsA", > "similarAccounts": [ > { > "id": "666411032", > "handle": "wwf", > "name": "WWF International", > "bio": null, > "avatarUrl": "https://scontent-ord5-1.cdninstagram.com/v/t51.2885-19/431325439_751480023713703_7991689382220454627_n.jpg?stp=dst-jpg_…", > "isVerified": true, > "followers": null, > "following": null, > "posts": null, > "website": null, > "location": null, > "category": null, > "url": "https://www.instagram.com/wwf/", > "isPrivate": false > } > ] > } > ``` ## instagram-comments An Instagram post, reel or share link. * **Example page:** [https://www.instagram.com/p/DeuOR-CjKE9/](https://www.instagram.com/p/DeuOR-CjKE9/) * **Returns:** A list of comments: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "18181102558431616", > "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18181102558431616/", > "author": { > "id": "49884965268", > "name": null, > "handle": "querosercomunista", > "url": "https://www.instagram.com/querosercomunista/", > "avatarUrl": "https://scontent-lga3-2.cdninstagram.com/v/t51.82787-19/886273225_18099923474661269_8757655740803320523_n.jpg?stp=dst-j…", > "isVerified": false > }, > "text": "#protejamnossospovosindigenas\n#PovosIndígenas #GuaraniKaiowá #protejaospovosindigenas #JustiçaNoCampo #exercitodolula", > "publishedAt": "2026-11-04T21:09:54.000Z", > "likes": 0, > "replies": null, > "parentId": null > } > ], > "cursor": "10:{\"is_server_cursor_inverse\":true,\"server_cursor\":\"AQHTFv6-89ZOdqGo5AVEcXB5FS2KMQ5cLMy0yXrFmnCR13uZQkYb14ygM3ZZOq0AYmf4eKqydxFov31-lbYljKoY5A\"}", > "page": null, > "total": null > } > ``` ## instagram-feed An Instagram hashtag, location or keyword search page, like instagram.com/explore/tags/travel. * **Example page:** [https://www.instagram.com/explore/tags/travel/](https://www.instagram.com/explore/tags/travel/) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "3809847048594935553", > "url": "https://www.instagram.com/p/DTfS7SMEk8B/", > "title": null, > "text": "Switzerland all the year 🇨🇭🥹\n\nWhich one is your preferred month?\n\n@life_samour_style \n\n#switzerland…", > "author": { > "id": "65543671366", > "name": null, > "handle": "life_samour_style", > "url": "https://www.instagram.com/life_samour_style/", > "avatarUrl": "https://scontent.cdninstagram.com/v/t51.82787-19/584635801_17922495753191367_8918713359859714107_n.jpg?stp=dst-jpg_s150…", > "isVerified": true > }, > "community": null, > "publishedAt": null, > "likes": null, > "comments": null, > "shares": null, > "views": 30250451, > "media": [ > { > "type": "video", > "url": "https://scontent-ord5-2.cdninstagram.com/o1/v/t2/f2/m86/AQP_hqF-tPtv5Xofan7SoZA6fFe5GfcwBPguliTCR2r7fcmzChiIeMjhkMYEEKZ…" > } > ], > "hashtags": [ > "switzerland", > "life_samour_style", > "season" > ], > "postCode": "DTfS7SMEk8B", > "type": "video", > "mentions": [ > "life_samour_style" > ], > "thumbnailUrl": "https://scontent-ord5-2.cdninstagram.com/v/t51.71878-15/615887274_3237902143054688_1140202660103312350_n.jpg?stp=dst-jp…", > "imageDescription": null, > "isPinned": false, > "taggedUsers": [], > "coauthors": [], > "audioTitle": null, > "audioArtist": null, > "audioIsOriginal": null, > "isPaidPartnership": false, > "sponsors": [] > } > ], > "cursor": "AQHTiwkWRKdj9US-Gs-xBpCM150qBhK7t3yVK2kgwTAZNNrYPGR9-ep2f4EEBsK-5rYV", > "page": null, > "total": null, > "name": "travel", > "relatedKeywords": [ > "transfer travel", > "time travel real", > "november travel destinations" > ], > "category": null, > "latitude": null, > "longitude": null > } > ``` ## x-profile An X profile page, like x.com/nasa. Send options view posts for the profile's posts. * **Example page:** [https://x.com/nasa](https://x.com/nasa) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "id": "11348282", > "url": "https://x.com/NASA", > "handle": "NASA", > "name": "NASA", > "bio": "Making the seemingly impossible, possible. ✨", > "avatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg", > "isVerified": true, > "followers": 92290226, > "following": 115, > "posts": 74493, > "website": "http://www.nasa.gov/", > "location": "Pale Blue Dot", > "category": null, > "joinedAt": "2007-12-19T20:20:32.000Z", > "verifiedType": "Government", > "isProtected": false, > "bannerUrl": "https://pbs.twimg.com/profile_banners/11348282/1788992290" > } > ``` ## x-post An X post page, like x.com/nasa/status/``. * **Example page:** [https://x.com/NASA/status/2118041009766678695](https://x.com/NASA/status/2118041009766678695) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "id": "2118041009766678695", > "url": "https://x.com/NASA/status/2118041009766678695", > "title": null, > "text": "Earlier today, @astro_anil spoke from the International Space Station with @MarkRober, taking questions from students…", > "author": { > "id": "11348282", > "name": "NASA", > "handle": "NASA", > "url": "https://x.com/NASA", > "avatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg", > "isVerified": true > }, > "community": null, > "publishedAt": "2026-11-04T18:01:42.000Z", > "likes": 488, > "comments": 45, > "shares": 65, > "views": 296964, > "media": [ > { > "type": "image", > "url": "https://pbs.twimg.com/media/HWSp9nzXsAAazfF.jpg?name=orig", > "thumbnailUrl": null, > "width": 1920, > "height": 1080, > "durationSeconds": null, > "altText": "An image of Anil Menon floating inside the International Space Station. Overlaid is the text \"Astronaut Anil Menon…" > } > ], > "hashtags": [], > "language": "en", > "quotes": 6, > "bookmarks": 25, > "mentions": [ > "astro_anil", > "MarkRober" > ], > "links": [ > "https://youtu.be/IhpBgLB8JUQ" > ], > "replyToUrl": null, > "quotedUrl": null, > "quotedText": null, > "quotedAuthorUsername": null, > "isEdited": false, > "isSensitive": false > } > ``` ## threads-profile A Threads profile page, like threads.com/@nasa. Send options view posts for the profile's posts. * **Example page:** [https://www.threads.com/@nasa](https://www.threads.com/@nasa) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "28829152388", > "url": "https://www.threads.com/@nasa", > "handle": "nasa", > "name": "NASA", > "bio": "Making the seemingly impossible, possible. ✨", > "avatarUrl": "https://scontent-iad6-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?stp=dst-jp…", > "isVerified": true, > "followers": 12787718, > "following": null, > "posts": 156, > "website": null, > "location": null, > "category": null, > "bioLinkUrls": [], > "isPrivate": false > } > ``` ## threads-post A Threads post page, like threads.com/@nasa/post/``. * **Example page:** [https://www.threads.com/@nasa/post/DfVbdbGAhkX](https://www.threads.com/@nasa/post/DfVbdbGAhkX) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "4023242611337861399", > "url": "https://www.threads.com/@nasa/post/DfVbdbGAhkX", > "title": null, > "text": "Spacewalk alert! \n\nTomorrow, Nov. 5, at 7 a.m. EST (1200 UTC), watch two astronauts install a roll-out solar array on…", > "author": { > "id": "28829152388", > "name": null, > "handle": "nasa", > "url": "https://www.threads.com/@nasa", > "avatarUrl": "https://scontent-lga3-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?stp=dst-jp…", > "isVerified": true > }, > "community": null, > "publishedAt": "2026-11-04T21:52:03.000Z", > "likes": 314, > "comments": 12, > "shares": 4, > "views": null, > "media": [ > { > "type": "image", > "url": "https://scontent-lga3-3.cdninstagram.com/v/t51.71878-15/890411991_1980590489581625_9124358272712272144_n.jpg?stp=dst-jp…" > } > ], > "hashtags": [], > "postCode": "DfVbdbGAhkX", > "reposts": 19, > "quotes": 4, > "imageDescription": null, > "quotedPostUrl": null, > "isPinned": true, > "commentList": [ > { > "url": "https://www.threads.com/@nasa/post/DfVdxsvAZrg", > "author": { > "id": "28829152388", > "name": null, > "handle": "nasa", > "url": "https://www.threads.com/@nasa", > "avatarUrl": "https://scontent-lga3-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?stp=dst-jp…", > "isVerified": true > }, > "text": "Set your alarm and tune in!", > "publishedAt": "2026-11-04T21:52:09.000Z", > "likes": 116, > "replies": 2, > "parentId": null, > "id": "4023252800761862880", > "postCode": "DfVdxsvAZrg", > "reposts": 5, > "quotes": 0, > "shares": 3, > "media": [ > { > "type": "link", > "url": "https://www.nasa.gov/live/", > "title": "NASA Live - NASA" > } > ], > "quotedPostUrl": null, > "isPinned": false > } > ], > "cursor": "eyJ0IjoiZG93bndhcmRfb3RoZXJfcmVwbGllcyIsInRzIjoxNzkzODMyMzgwNDQ0LCJleCI6WzE4MDk1ODU1NTA0NDY3MTE1LDE3OTQyMTI0NTEzMzg5NjA0LDE4MTYwMzAyODI5NDQ5NTk4LDE4NjQ4MzQ3M..." > } > ``` ## pinterest-search A Pinterest pin or video search page with a q query, like pinterest.com/search/pins/?q=kitchen. * **Example page:** [https://www.pinterest.com/search/pins/?q=kitchen%20ideas](https://www.pinterest.com/search/pins/?q=kitchen%20ideas) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `type`, `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "https://www.tilebar.com/montauk-gin-2x8-ceramic-wall-tile-satin.html", > "url": "https://www.tilebar.com/montauk-gin-2x8-ceramic-wall-tile-satin.html", > "title": "Explore Montauk Gin 2x8 White Ceramic Subway Wall Tile with Mixed Finish", > "text": "The Montauk Gin 2x8 White Ceramic Wall Tile reimagines the subway format in durable ceramic-with a distinctively…", > "author": { > "id": "101049722797560631", > "name": "TileBar", > "handle": "TileBar", > "url": "https://www.pinterest.com/TileBar/", > "avatarUrl": "https://i.pinimg.com/140x140_RS/8f/8a/2c/8f8a2c4d5a9240a454dd99d3703bc0eb.jpg", > "isVerified": null > }, > "community": { > "name": "Tiles & Backsplashes", > "url": "https://www.pinterest.com/TileBar/tiles-backsplashes/" > }, > "publishedAt": "2024-01-14T07:22:59.000Z", > "likes": 63, > "comments": null, > "shares": null, > "views": null, > "media": [ > { > "type": "image", > "url": "https://i.pinimg.com/originals/bc/54/e8/bc54e89cd5e3e093314c3349401ec38e.png", > "width": 1000, > "height": 1600, > "altText": "a kitchen with wooden cabinets and white counter tops", > "durationSeconds": null > } > ], > "hashtags": [], > "saves": null, > "linkUrl": "https://www.tilebar.com/montauk-gin-2x8-ceramic-wall-tile-satin.html", > "domain": "tilebar.com", > "dominantColor": "#846c4c", > "isPromoted": false, > "boardId": "101049654078317541" > } > ], > "cursor": "Y2JVSG81V2sxcmNHRlpWM1J5VFVad1YxWllaR3hpVmtZMldWVlZNVll4U2xkWFZFSlhVbnBHTTFVeWN6RlNhelZXVm14S1dGSXlhRkpXVjNSV1pVVTFSMVZZYUZaaVZGWlFWbXhvVTJWV1pISlhhM1JYVm10V...", > "page": null, > "total": null > } > ``` ## pinterest-pin A Pinterest pin page or a pin.it short link. * **Example page:** [https://www.pinterest.com/pin/32088216099796013/](https://www.pinterest.com/pin/32088216099796013/) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "id": "32088216099796013", > "url": "https://www.pinterest.com/pin/32088216099796013/", > "title": "Can You Use Leaves From a Diseased Tree as Mulch? Gardening Experts Explain", > "text": "Can you use leaves from a diseased tree as mulch? Gardening experts explain the risks of spreading disease, how to…", > "author": { > "id": "32088353503445352", > "name": "Martha Stewart", > "handle": "marthastewart", > "url": "https://www.pinterest.com/marthastewart/", > "avatarUrl": "https://i.pinimg.com/75x75_RS/c8/11/4c/c8114c783347e27daef00e5d4a6ac4f3.jpg", > "isVerified": true > }, > "community": { > "name": "Winter Bucket List", > "url": "https://www.pinterest.com/marthastewart/winter-bucket-list/" > }, > "publishedAt": "2026-11-04T21:00:13.000Z", > "likes": 0, > "comments": 0, > "shares": 0, > "views": null, > "media": [ > { > "type": "image", > "url": "https://i.pinimg.com/originals/a0/52/fc/a052fc0ce0f443106204734be2029f83.jpg", > "width": 1000, > "height": 664, > "altText": null, > "durationSeconds": null > } > ], > "hashtags": [], > "saves": 1, > "linkUrl": "https://www.marthastewart.com/can-you-use-leaves-from-a-diseased-tree-12222151?utm_campaign=marthastewart_6aeb9cdcb763f…", > "domain": "marthastewart.com", > "dominantColor": "#394d1f", > "isPromoted": false, > "boardId": "32088284784293638" > } > ``` ## pinterest-board A Pinterest board page, like pinterest.com/``/``/. * **Example page:** [https://www.pinterest.com/TileBar/tiles-backsplashes/](https://www.pinterest.com/TileBar/tiles-backsplashes/) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "https://www.tilebar.com/product/terrazzo-italy-fluted-sacra-calacatta-white-12x24-honed-terrazzo-tile.html", > "url": "https://www.tilebar.com/product/terrazzo-italy-fluted-sacra-calacatta-white-12x24-honed-terrazzo-tile.html", > "title": "Calacatta White Honed Terrazzo Tile for Bathroom Renovation", > "text": "Want to renovate your home bathroom? This Terrazzo Italy Fluted Sacra Calacatta White 12x24 Honed Terrazzo Tile from…", > "author": { > "id": "101049722797560631", > "name": "TileBar", > "handle": "TileBar", > "url": "https://www.pinterest.com/TileBar/", > "avatarUrl": "https://i.pinimg.com/140x140_RS/8f/8a/2c/8f8a2c4d5a9240a454dd99d3703bc0eb.jpg", > "isVerified": null > }, > "community": { > "name": "Tiles & Backsplashes", > "url": "https://www.pinterest.com/TileBar/tiles-backsplashes/" > }, > "publishedAt": "2026-03-06T14:16:20.000Z", > "likes": 0, > "comments": null, > "shares": 0, > "views": null, > "media": [ > { > "type": "image", > "url": "https://i.pinimg.com/originals/e7/bc/db/e7bcdb0fd74dd6f5ed330aeaaa7fe15b.jpg", > "width": 1200, > "height": 1200, > "altText": "a bathroom with marble counter top and white wall tiles on the walls, along with a black faucet", > "durationSeconds": null > } > ], > "hashtags": [], > "saves": 1, > "linkUrl": "https://www.tilebar.com/product/terrazzo-italy-fluted-sacra-calacatta-white-12x24-honed-terrazzo-tile.html", > "domain": "tilebar.com", > "dominantColor": "#b0aca5", > "isPromoted": false, > "boardId": "101049654078317541" > } > ], > "cursor": "Y2JZakk0ZVU1WWR6Vk5ha1V5VFZSVk0wMTZVVE5OYWxsNVQwUnJNRXRyWkZKVVEzQTRUVEpSZUUweVJYaFBSMWt4V1hwVk1Wa3lUbWhhUkVFMVRXcFplVTVVUVROTlYwcHRXWHBvYWsxNlpHMU5SMXB0V2xSQ...", > "page": null, > "total": null, > "board": { > "id": "101049654078317541", > "url": "https://www.pinterest.com/TileBar/tiles-backsplashes/", > "name": "Tiles & Backsplashes", > "description": "This board is all about Tiles and Backsplashes. Here, we gather the best tile ideas and backsplashes for kitchen and…", > "category": "home_decor", > "pins": 1261, > "followers": 78214, > "sections": 3, > "thumbnailUrl": "https://i.pinimg.com/custom_covers/200x150/101049654078317541_1609554349.jpg", > "owner": { > "id": "101049722797560631", > "name": "TileBar", > "handle": "TileBar", > "url": "https://www.pinterest.com/TileBar/", > "avatarUrl": "https://i.pinimg.com/280x280_RS/8f/8a/2c/8f8a2c4d5a9240a454dd99d3703bc0eb.jpg", > "isVerified": null > } > } > } > ``` ## pinterest-profile A Pinterest profile page, like pinterest.com/marthastewart/. * **Example page:** [https://www.pinterest.com/marthastewart/](https://www.pinterest.com/marthastewart/) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "32088353503445352", > "url": "https://www.pinterest.com/marthastewart/", > "handle": "marthastewart", > "name": "Martha Stewart", > "bio": "Daily recipes, crafts, and inspiration from Martha Stewart.", > "avatarUrl": "https://i.pinimg.com/280x280_RS/c8/11/4c/c8114c783347e27daef00e5d4a6ac4f3.jpg", > "isVerified": true, > "followers": 1867764, > "following": 321, > "posts": 105728, > "website": "http://marthastewart.com", > "location": null, > "category": null, > "boards": 174, > "isPrivate": false, > "createdAt": "2011-09-15T07:56:17.000Z", > "recentPins": [ > { > "title": "10 Things to Clean in November Before Winter-and Holiday Guests-Arrive", > "text": "Tackle these November cleaning tasks now to prepare your home for colder weather, holiday guests, and the busy season…", > "author": { > "id": "32088353503445352", > "name": "Martha Stewart", > "handle": "marthastewart", > "url": "https://www.pinterest.com/marthastewart/", > "avatarUrl": "https://i.pinimg.com/140x140_RS/c8/11/4c/c8114c783347e27daef00e5d4a6ac4f3.jpg", > "isVerified": true > }, > "community": { > "name": "Fresh Fall Ideas", > "url": "https://www.pinterest.com/herbacinusa/fresh-fall-ideas/" > }, > "publishedAt": "2026-11-04T23:00:13.000Z", > "likes": 0, > "comments": null, > "shares": null, > "views": null, > "media": [ > { > "type": "image", > "url": "https://i.pinimg.com/originals/b9/97/6d/b9976d19f1e2aade04b87e13eacbf012.jpg", > "width": 1000, > "height": 667, > "altText": null, > "durationSeconds": null > } > ], > "hashtags": [], > "id": "49328558415048996", > "url": "https://www.pinterest.com/pin/49328558415048996/", > "saves": 1, > "linkUrl": "https://www.marthastewart.com/things-to-clean-in-november-12208381?utm_campaign=marthastewart_6aebb8fdb763fd0001a28b53&…", > "domain": "marthastewart.com", > "dominantColor": "#aeb1b6", > "isPromoted": false, > "boardId": "49328627107623443" > } > ], > "cursor": "P2MzMjA4ODIxNjA5OTc5MDE2NC4xNzkzNTg0ODEyLC0xfDI0fDE0NDU0NzkxOTYwMDg5MDcqR1FMKnw4YjJhN2FjYjhmNGIwNWNmMDE2ZjgwOWFiNDUwMDY4N2ZlMTBlMGE2ZjE1MGU1YTBmMTljODBhMmRhM..." > } > ``` ## facebook-page A Facebook page, like facebook.com/NASA. Send options view posts for the page's posts. * **Example page:** [https://www.facebook.com/NASA](https://www.facebook.com/NASA) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "54971236771", > "url": "https://www.facebook.com/NASA", > "handle": "NASA", > "name": "NASA - National Aeronautics and Space Administration", > "bio": "Explore the universe and discover our home planet. \nThere's space for everybody. ✨", > "avatarUrl": "https://scontent.ffcm1-1.fna.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png&cs…", > "isVerified": true, > "followers": 28733329, > "following": null, > "posts": null, > "website": "https://www.nasa.gov/nasa-app/", > "location": null, > "category": "Government organization", > "likes": null, > "talkingAboutThis": 76844, > "phone": null, > "email": "name@example.com", > "websites": [ > "https://www.nasa.gov/nasa-app/", > "https://www.nasa.gov/" > ], > "priceRange": null, > "coverUrl": "https://scontent.ffcm1-1.fna.fbcdn.net/v/t39.99422-6/809146614_4484013928506139_3181913787670602881_n.png?stp=dst-jpg_t…" > } > ``` ## facebook-post A Facebook post, reel or video page, or an fb.watch link. * **Example page:** [https://www.facebook.com/NASA/posts/pfbid02gQRwwY2RMZvcRYS9eqkWDBm9idv46oRRVvPFvtsPu9UyoHiukHQ6PjWwfKE4TKXQl](https://www.facebook.com/NASA/posts/pfbid02gQRwwY2RMZvcRYS9eqkWDBm9idv46oRRVvPFvtsPu9UyoHiukHQ6PjWwfKE4TKXQl) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "1675983783896991", > "url": "https://www.facebook.com/NASA/posts/pfbid02gQRwwY2RMZvcRYS9eqkWDBm9idv46oRRVvPFvtsPu9UyoHiukHQ6PjWwfKE4TKXQl", > "title": null, > "text": "Pspsps 🐈‍⬛\n\nThis smoky specter is the Cat’s Head Nebula, captured in intricate detail by NASA's James Webb Space…", > "author": { > "id": "100044561550831", > "name": "NASA - National Aeronautics and Space Administration", > "handle": null, > "url": "https://www.facebook.com/NASA", > "avatarUrl": null, > "isVerified": null > }, > "community": null, > "publishedAt": "2026-11-03T15:00:35.000Z", > "likes": 40579, > "comments": 461, > "shares": 2982, > "views": null, > "media": [ > { > "type": "image", > "url": "https://www.facebook.com/photo/?fbid=1675983760563660&set=a.416661013162614", > "thumbnailUrl": null, > "width": 780, > "height": 540, > "durationSeconds": null, > "altText": "An intricate cloud of white dust takes center stage in this photo, rising in a windy pillar. The background features…" > } > ], > "hashtags": [], > "reactions": { > "total": 40579, > "like": 19171, > "love": 20339, > "care": 688, > "haha": 105, > "wow": 264, > "sad": 6, > "angry": 6 > } > } > ``` ## facebook-comments A Facebook post, reel or video page, or an fb.watch link. * **Example page:** [https://www.facebook.com/NASA/posts/pfbid02gQRwwY2RMZvcRYS9eqkWDBm9idv46oRRVvPFvtsPu9UyoHiukHQ6PjWwfKE4TKXQl](https://www.facebook.com/NASA/posts/pfbid02gQRwwY2RMZvcRYS9eqkWDBm9idv46oRRVvPFvtsPu9UyoHiukHQ6PjWwfKE4TKXQl) * **Returns:** A list of comments: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "2183521102234620", > "url": "https://www.facebook.com/NASA/posts/pfbid02gQRwwY2RMZvcRYS9eqkWDBm9idv46oRRVvPFvtsPu9UyoHiukHQ6PjWwfKE4TKXQl?comment_id…", > "author": { > "id": "pfbid08A6i4dhDgpr5QkSeW6sfBtKYQ1ypYCeZfbTcpKY27ZaiqT55Lb3DM5TgNYvApsUPl", > "name": "Jessica Emerson", > "handle": null, > "url": null, > "avatarUrl": null, > "isVerified": null > }, > "text": "The cat in the universe with us?", > "publishedAt": "2026-11-04T23:06:16.000Z", > "likes": 0, > "replies": 0, > "parentId": null > } > ], > "cursor": "ZmVlZGJhY2s6cGZiaWQwMmdRUnd3WTJSTVp2Y1JZUzllcWtXREJtOWlkdjQ2b1JSVnZQRnZ0c1B1OVV5b0hpdWtIUTZQald3ZktFNFRLWFFs~MToxNzkzODMzODYzOgF_QLZKvBZtiymNIVIz5ArlLSoxKLDp...", > "page": null, > "total": null > } > ``` ## linkedin-company A LinkedIn company page. * **Example page:** [https://www.linkedin.com/company/microsoft](https://www.linkedin.com/company/microsoft) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "microsoft", > "url": "https://www.linkedin.com/company/microsoft", > "handle": "microsoft", > "name": "Microsoft", > "bio": "Every company has a mission. What's ours? To empower every person and every organization to achieve more. We believe…", > "avatarUrl": null, > "isVerified": null, > "followers": 29449322, > "following": null, > "posts": null, > "website": "https://news.microsoft.com/", > "location": "Redmond, Washington", > "category": "Software Development", > "size": "10,001+ employees", > "employees": 231124, > "specialties": [ > "Business Software", > "Developer Tools", > "Home & Educational Software" > ], > "founded": null > } > ``` ## linkedin-profile A LinkedIn profile page. * **Example page:** [https://www.linkedin.com/in/satyanadella](https://www.linkedin.com/in/satyanadella) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "satyanadella", > "url": "https://www.linkedin.com/in/satyanadella", > "handle": "satyanadella", > "name": "Satya Nadella", > "bio": "As chairman and CEO of Microsoft, I define my mission and that of my company as empowering every person and every…", > "avatarUrl": null, > "isVerified": null, > "followers": 12285841, > "following": null, > "posts": null, > "website": null, > "location": "Redmond, Washington, United States", > "category": null, > "headline": "Chairman and CEO at Microsoft", > "isAboutTruncated": false, > "roles": [ > { > "title": "Chairman and CEO", > "companyName": "Microsoft", > "companyUrl": "https://www.linkedin.com/company/microsoft", > "from": "Feb 2014", > "to": null, > "isCurrent": true > } > ], > "education": [ > { > "school": "The University of Chicago Booth School of Business", > "degree": null, > "schoolUrl": "https://www.linkedin.com/school/universityofchicagoboothschoolofbusiness", > "from": "1994", > "to": "1996" > } > ] > } > ``` ## linkedin-posts A LinkedIn profile or company page. * **Example page:** [https://www.linkedin.com/company/microsoft](https://www.linkedin.com/company/microsoft) * **Returns:** A list of posts: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7523429494351912961", > "url": "https://www.linkedin.com/feed/update/urn:li:activity:7523429494351912961", > "title": null, > "text": "Please join us at Microsoft Ignite, our biggest customer and partner event of the year, from November 17-20 in San…", > "author": { > "id": null, > "name": "Judson Althoff", > "handle": null, > "url": "https://www.linkedin.com/in/judsonalthoff", > "avatarUrl": null > }, > "community": null, > "publishedAt": "2026-11-03T17:02:50.014Z", > "likes": 1782, > "comments": 61, > "shares": null, > "views": null, > "media": [], > "hashtags": [] > } > ], > "cursor": "microsoft.1035.0-1793832213252-aa05c4b5e106b1ca7be9ef0dddc8a891.10", > "page": null, > "total": null > } > ``` # Video Source: https://docs.stophy.dev/sources/video Search YouTube and TikTok, open any video, channel or playlist, and read comments. Get transcripts from YouTube, TikTok and Instagram videos. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.youtube.com/results?search_query=lofi+beats","formats":[{"type":"json","parser":"youtube-search"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://www.youtube.com/results?search_query=lofi+beats", formats: [{ type: "json", parser: "youtube-search" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://www.youtube.com/results?search_query=lofi+beats", "formats": [{"type": "json", "parser": "youtube-search"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "youtube-search", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`youtube-search`](#youtube-search) | A YouTube search results page with the search in search\_query. | 1 credit per call. | | [`youtube-video`](#youtube-video) | A YouTube video link: watch, youtu.be, shorts or live. | 1 credit per call. | | [`youtube-transcript`](#youtube-transcript) | A YouTube video link: watch, youtu.be, shorts or live. | 1 credit per call. | | [`youtube-comments`](#youtube-comments) | A YouTube video link: watch, youtu.be, shorts or live. | 1 credit per call. | | [`youtube-channel`](#youtube-channel) | A YouTube channel link: @handle, /channel/, /c/ or /user/, with an optional tab. | 1 credit per call. | | [`youtube-post`](#youtube-post) | A YouTube community post link: /post/Ugkx... | 1 credit per call. | | [`youtube-playlist`](#youtube-playlist) | A YouTube playlist page with list in the link. | 1 credit per call. | | [`tiktok-video`](#tiktok-video) | A TikTok video page or share link. | 1 credit per call. | | [`tiktok-comments`](#tiktok-comments) | A TikTok video page or share link. | 1 credit per call. | | [`tiktok-transcript`](#tiktok-transcript) | A TikTok video page or share link. | 1 credit when the video has captions; otherwise 2 credits plus 1 credit for every 10 seconds of audio, up to 3 minutes. | | [`tiktok-profile`](#tiktok-profile) | A TikTok profile page. | 1 credit per call. | | [`tiktok-hashtag`](#tiktok-hashtag) | A TikTok hashtag page. | 1 credit per call. | | [`tiktok-sound`](#tiktok-sound) | A TikTok sound page that ends in the sound id. | 1 credit per call. | | [`tiktok-search`](#tiktok-search) | A TikTok user search page (/search/user) or video search page (/search) with a q query. | 1 credit per call. | | [`tiktok-followers`](#tiktok-followers) | A TikTok profile page. | 1 credit per call. | | [`tiktok-following`](#tiktok-following) | A TikTok profile page. | 1 credit per call. | | [`instagram-transcript`](#instagram-transcript) | An Instagram reel or video post. | 1 credit plus 1 credit for every 30 seconds of audio, up to 5 minutes. | ## youtube-search A YouTube search results page with the search in search\_query. * **Example page:** [https://www.youtube.com/results?search\_query=lofi+beats](https://www.youtube.com/results?search_query=lofi+beats) * **Returns:** A list of videos: `results`, `cursor`, `page`, `total`. * **Options:** `type` (Leave out for videos, channels and playlists. Use shorts for Shorts), `duration`, `uploadDate`, `features`, `prioritize`, `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "RDEMB4pXSfqexQjAYE27XBWebA", > "url": "https://www.youtube.com/playlist?list=RDEMB4pXSfqexQjAYE27XBWebA", > "title": "Mix - Lo-Fi Beats", > "description": null, > "author": { > "id": null, > "name": null, > "handle": null, > "url": null, > "avatarUrl": null > }, > "publishedAt": null, > "durationSeconds": null, > "views": null, > "likes": null, > "comments": null, > "thumbnailUrl": "https://i.ytimg.com/vi/xVf4Zk8CBj0/hq720.jpg?sqp=-oaymwExCNAFEJQDSFryq4qpAyMIARUAAIhCGAHwAQH4Af4JgALQBYoCDAgAEAEYOSBhKG…", > "hashtags": [], > "type": "playlist", > "videoCount": null > } > ], > "cursor": "seen_88e6f353-7668-4a45-be2f-ee006bafacc9", > "page": null, > "total": null > } > ``` ## youtube-video A YouTube video link: watch, youtu.be, shorts or live. * **Example page:** [https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ) * **Returns:** One video: `id`, `url`, `title`, `description`, `author`, `publishedAt`, `durationSeconds`, `views`, `likes`, `comments`, `thumbnailUrl`, `hashtags`. * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "id": "dQw4w9WgXcQ", > "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", > "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", > "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this…", > "author": { > "id": "UCuAXFkgsw1L7xaCfnd5JJOw", > "name": "Rick Astley", > "handle": "RickAstleyYT", > "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw", > "avatarUrl": null > }, > "publishedAt": "2009-10-25T06:57:33.000Z", > "durationSeconds": 213, > "views": 1833745427, > "likes": 19491332, > "comments": 2400000, > "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", > "hashtags": [], > "isShort": false, > "isLive": false, > "category": "Music", > "tags": [ > "rick astley", > "Never Gonna Give You Up", > "nggyu" > ], > "channelSubscribers": 4560000, > "chapters": [], > "mostReplayedAtSeconds": [ > 2 > ] > } > ``` ## youtube-transcript A YouTube video link: watch, youtu.be, shorts or live. * **Example page:** [https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ) * **Returns:** `startSeconds`, `endSeconds`, `text`. * **Options:** `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `includeTimestamps`. * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "videoId": "dQw4w9WgXcQ", > "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", > "language": "en", > "isAutoGenerated": false, > "durationSeconds": 213, > "text": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules and so do I ♪ ♪ A full commitment's what I'm thinking of ♪ ♪…" > } > ``` ## youtube-comments A YouTube video link: watch, youtu.be, shorts or live. * **Example page:** [https://www.youtube.com/watch?v=dQw4w9WgXcQ](https://www.youtube.com/watch?v=dQw4w9WgXcQ) * **Returns:** A list of comments: `results`, `cursor`, `page`, `total`. * **Options:** `comment` (A comment's repliesCursor from an earlier response. Returns that comment's replies), `sort`, `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "UgyEnXfdC-umwvTt8JF4AaABAg", > "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&lc=UgyEnXfdC-umwvTt8JF4AaABAg", > "author": { > "id": "UCWf34D_s8K_m2vwBISIDWtg", > "name": "Oatman69", > "handle": "Oatman69", > "url": "https://www.youtube.com/channel/UCWf34D_s8K_m2vwBISIDWtg", > "avatarUrl": null > }, > "text": "Gonna flag this for nudity so I can rick roll the YouTube staff", > "publishedAt": "2020-01-01T00:00:00.000Z", > "likes": 569000, > "replies": 726, > "parentId": null, > "isPinned": false, > "isHearted": false, > "isChannelOwner": false, > "repliesCursor": "Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIaVWd5RW5YZmRDLXVtd3ZUdDhKRjRBYUFCQWciAggAKhhVQ3VBWEZrZ3N3MUw3eGFDZm5kNUpKT3cyC2RRdzR3OVd…" > } > ], > "cursor": "Eg0SC2RRdzR3OVdnWGNRGAYy_gIK1AJnZXRfcmFua2VkX3N0cmVhbXMtLUNxWUJDSUFFRlJlMzBUZ2Ftd0VLbGdFSTJGOFFnQVFZQnlLTEFWdDhhbWV6S3llMWJCOXJJR3BXbmlPZVpDbFJpRDBvc2JZX0FPY...", > "page": null, > "total": null > } > ``` ## youtube-channel A YouTube channel link: @handle, /channel/, /c/ or /user/, with an optional tab. * **Example page:** [https://www.youtube.com/@mkbhd](https://www.youtube.com/@mkbhd) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `tab` (YouTube's own channel tab. Releases are a music channel's albums), `sort` (YouTube's own sort for the videos, shorts and live tabs), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "id": "UCBJycsmduvYEL83R_U4JriQ", > "url": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ", > "handle": "mkbhd", > "name": "Marques Brownlee", > "bio": "MKBHD: Quality Tech Videos | YouTuber | Geek | Consumer Electronics | Tech Head | Internet Personality!\n…", > "avatarUrl": "https://yt3.googleusercontent.com/qu4TmIaYUlS41-dJ9gZ7DUR3nilvmB5_11i6OKSdvNnBNiyOusZP1bMN6ICnuxtjFBb6ioKgRQ=s900-c-k-c…", > "isVerified": null, > "followers": 21400000, > "following": null, > "posts": 1800, > "website": null, > "location": "United States", > "category": null, > "bannerUrl": "https://yt3.googleusercontent.com/zi_48HwHU4s0Hnb6tZuvRzTfCPHrLEnrtIMDLzMauDEyDmURh9JZ4wrNd3lKr7m9uVnT4YjYKw=w2560-fcro…", > "joinedDate": "2008-03-21", > "totalViews": 5868481445, > "results": [ > { > "description": null, > "likes": null, > "comments": null, > "type": "video", > "title": "OLED iPad Mini is The Most Apple Product They've Ever Appled", > "durationSeconds": 780, > "views": 7500000, > "thumbnailUrl": "https://i.ytimg.com/vi/g6Die8gVFn0/hqdefault.jpg", > "isShort": false, > "isLive": false, > "publishedAt": "2026-11-03T00:00:00.000Z", > "id": "g6Die8gVFn0", > "url": "https://www.youtube.com/watch?v=g6Die8gVFn0", > "author": { > "id": "UCBJycsmduvYEL83R_U4JriQ", > "name": "Marques Brownlee", > "handle": "mkbhd", > "url": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ", > "avatarUrl": null > }, > "hashtags": [] > } > ], > "cursor": "4qmFsgLZCRIYVUNCSnljc21kdXZZRUw4M1JfVTRKcmlRGrwJOGdhRUJ4cUJCM3ItQmpyN0Jnb2tObUkxTTJJNFpqSXRNREF3TUMweU5URmpMV0l6Tm1JdE5UZ3lOREk1WTJJME5ESXdFdEFHUVdOV09GWmtWe..." > } > ``` ## youtube-post A YouTube community post link: /post/Ugkx... or a community page with ?lb=. * **Example page:** [https://www.youtube.com/post/UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ](https://www.youtube.com/post/UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ) * **Returns:** One post: `id`, `url`, `title`, `text`, `author`, `community`, `publishedAt`, `likes`, `comments`, `shares`, `views`, `media`, `hashtags`. * **Options:** `sort` (YouTube's own comment sort), `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ", > "url": "https://www.youtube.com/post/UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ", > "title": null, > "text": "Alright, it's that time: https://vote.mkbhd.com\n\nWelcome to the Blind Smartphone Camera Test 2023! 20 smartphones. 3…", > "author": null, > "community": null, > "publishedAt": "2024-01-01T00:00:00.000Z", > "likes": 12000, > "comments": 1043, > "shares": null, > "views": null, > "media": [ > { > "type": "image", > "url": "https://yt3.ggpht.com/zy6PEg0QzlzFe8xfDxpAbe1mGV0pXgc-xV1MvQ7rlf_EWjEj_YqN0Y2b7fiaOCdghICsMxy8tDGDaA=s1516-rw-nd-v1" > } > ], > "hashtags": [], > "videoId": null, > "videoTitle": null, > "pollChoices": [], > "pollTotalVotes": null, > "commentList": [ > { > "text": "waiting for the new video, \"Let's Talk About Vehicular Felonies.\"", > "likes": 204, > "replies": 2, > "publishedAt": "2025-01-01T00:00:00.000Z", > "isPinned": false, > "isHearted": false, > "isChannelOwner": false, > "repliesCursor": "4qmFsgLQAhIrRkVjb21tZW50X3Bvc3RfZGV0YWlsX3BhZ2Vfd2ViX3JlcGxpZXNfcGFnZRqgAkVnVndiM04wYzhvQko3SUJKRlZuYTNoWU5tZHJSSGhSTUV…", > "id": "Ugwy052tBWynxReFHN94AaABAg", > "url": "https://www.youtube.com/post/UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ?lc=Ugwy052tBWynxReFHN94AaABAg", > "author": { > "id": "UCjU-RRrNmxYVD5RpCuaKZBw", > "name": "Kirkenheimer15", > "handle": "Kirkenheimer15", > "url": "https://www.youtube.com/channel/UCjU-RRrNmxYVD5RpCuaKZBw", > "avatarUrl": null > }, > "parentId": null > } > ], > "cursor": "4qmFsgKFBRIoRkVjb21tZW50X3Bvc3RfZGV0YWlsX3BhZ2Vfd2ViX3RvcF9sZXZlbBrYBEVnVndiM04wYzZvRHR3TUswd0puWlhSZmNtRnVhMlZrWDNOMGNtVmhiWE10TFVOeFZVSkRTVUZGUmxKbE16QlVaM..." > } > ``` ## youtube-playlist A YouTube playlist page with list in the link. * **Example page:** [https://www.youtube.com/playlist?list=PLFgquLnL59alCl\_2TQvOiD5Vgm1hCaGSI](https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI) * **Returns:** A list of videos: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "fOT0BUpITw8", > "url": "https://www.youtube.com/watch?v=fOT0BUpITw8", > "title": "BELLAKEO (Video Oficial) - Peso Pluma, Anitta", > "description": null, > "author": { > "id": "UCzrM_068Odho89mTRrrxqbA", > "name": "Peso Pluma", > "handle": null, > "url": "https://www.youtube.com/channel/UCzrM_068Odho89mTRrrxqbA", > "avatarUrl": null > }, > "publishedAt": "2024-01-01T00:00:00.000Z", > "durationSeconds": 235, > "views": 774000000, > "likes": null, > "comments": null, > "thumbnailUrl": "https://i.ytimg.com/vi/fOT0BUpITw8/hqdefault.jpg", > "hashtags": [], > "type": "video", > "isShort": false, > "isLive": false > } > ], > "cursor": "4qmFsgKBARIkVkxQTEZncXVMbkw1OWFsQ2xfMlRRdk9pRDVWZ20xaENhR1NJGjRDQUY2SGxCVU9rTkhVV2xGUlZrMVVXdGFRazFVWXpOT1JFazFUWHBSZVU5RVdRJTNEJTNEmgIiUExGZ3F1TG5MNTlhbENsX...", > "page": null, > "total": 182, > "playlist": { > "id": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI", > "url": "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI", > "title": "Popular Music Videos", > "description": null, > "author": { > "id": "UC-9-kyTW8ZkZNDHQJ6FgpwQ", > "name": "Music", > "handle": null, > "url": "https://www.youtube.com/channel/UC-9-kyTW8ZkZNDHQJ6FgpwQ", > "avatarUrl": null > }, > "videoCount": 182, > "views": 1045675568, > "hiddenVideos": 0, > "thumbnailUrl": "https://i.ytimg.com/vi/fOT0BUpITw8/hqdefault.jpg" > } > } > ``` ## tiktok-video A TikTok video page or share link. * **Example page:** [https://www.tiktok.com/@charlidamelio/video/7137423965982592302](https://www.tiktok.com/@charlidamelio/video/7137423965982592302) * **Returns:** One video: `id`, `url`, `title`, `description`, `author`, `publishedAt`, `durationSeconds`, `views`, `likes`, `comments`, `thumbnailUrl`, `hashtags`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "id": "7137423965982592302", > "url": "https://www.tiktok.com/@charlidamelio/video/7137423965982592302", > "title": null, > "description": null, > "author": { > "id": "5831967", > "name": "charli d’amelio", > "handle": "charlidamelio", > "url": "https://www.tiktok.com/@charlidamelio", > "avatarUrl": "https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:7…", > "isVerified": true > }, > "publishedAt": "2022-08-29T22:10:18.000Z", > "durationSeconds": 11, > "views": 22000000, > "likes": 2100000, > "comments": 19000, > "thumbnailUrl": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/c1844bce7c5a4b07b0e4ae2301a1996a~tplv-tiktokx-origin.ima…", > "hashtags": [], > "type": "video", > "mentions": [], > "imageUrls": [], > "shares": 17300, > "saves": 83186, > "audioId": "7090403288818584347", > "audioTitle": "Streets x Kiss it better", > "audioArtist": ":p", > "audioIsOriginal": true, > "isAd": false, > "isAiGenerated": false, > "country": "US", > "downloadUrl": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-ve-37c799-sg/f7803ec144cb492986bb4b6056003a3c/?a=1988&bti…", > "watermarkedDownloadUrl": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/tos-alisg-ve-37c799-sg/0641e3a6387a49e4a2c8c4de2c457fe8/?a=1988&bti…", > "downloadExpiresAt": "2026-11-06T23:11:21.000Z", > "downloadHeaders": { > "referer": "https://www.tiktok.com/", > "cookie": "tt_chain_token=jE4h20rgHlMmu7QChS5S5Q==" > }, > "audioUrl": "https://v45.tiktokcdn-eu.com/852d1747fbc73b4bca955665607a30e5/6aed0d19/video/tos/no1a/tos-no1a-v-2370c710-no/1643bebb34…", > "width": 576, > "height": 1024, > "quality": "540p" > } > ``` ## tiktok-comments A TikTok video page or share link. * **Example page:** [https://www.tiktok.com/@charlidamelio/video/7137423965982592302](https://www.tiktok.com/@charlidamelio/video/7137423965982592302) * **Returns:** A list of comments: `results`, `cursor`, `page`, `total`. * **Options:** `comment`, `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7137510823549272878", > "url": null, > "author": { > "id": "6811167419379434502", > "name": "🤓", > "handle": "your.mom4573", > "url": "https://www.tiktok.com/@your.mom4573", > "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352895290313015339~tplv-tiktokx-cropcenter:100:100.jp…" > }, > "text": "Charli Barker", > "publishedAt": "2022-08-30T03:47:36.000Z", > "likes": 5162, > "replies": 45, > "parentId": null, > "imageUrls": [] > } > ], > "cursor": "seen_0ee8c910-1f0c-4385-9f41-8843d5ff878b", > "page": null, > "total": null > } > ``` ## tiktok-transcript A TikTok video page or share link. * **Example page:** [https://www.tiktok.com/@charlidamelio/video/7137423965982592302](https://www.tiktok.com/@charlidamelio/video/7137423965982592302) * **Returns:** `startSeconds`, `endSeconds`, `text`. * **Options:** `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `includeTimestamps`. * **Price:** 1 credit when the video has captions; otherwise 2 credits plus 1 credit for every 10 seconds of audio, up to 3 minutes. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "videoId": "7137423965982592302", > "videoUrl": "https://www.tiktok.com/@charlidamelio/video/7137423965982592302", > "language": "en", > "isAutoGenerated": true, > "durationSeconds": 11.12375, > "transcribedSeconds": 12, > "text": "First time, first time, first time, look you in your eyes What are you willing to do? Oh, tell me what you're willing…" > } > ``` ## tiktok-profile A TikTok profile page. Send options view videos to page through its videos. * **Example page:** [https://www.tiktok.com/@khaby.lame](https://www.tiktok.com/@khaby.lame) * **Returns:** One profile: `id`, `url`, `handle`, `name`, `bio`, `avatarUrl`, `isVerified`, `followers`, `following`, `posts`, `website`, `location`, `category`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "id": "127905465618821121", > "url": "https://www.tiktok.com/@khaby.lame", > "handle": "khaby.lame", > "name": "Khabane lame", > "bio": "Se vuoi ridere sei nel posto giusto😎 If u wanna laugh u r in the right place😎", > "avatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…", > "isVerified": true, > "followers": 162955695, > "following": 82, > "posts": 1359, > "website": null, > "location": null, > "category": null, > "likes": 2692469127, > "isPrivate": false, > "isOrganization": false, > "language": "en", > "createdAt": "2016-08-10T22:02:34.000Z", > "videos": [ > { > "id": "7697307919943060767", > "url": "https://www.tiktok.com/@khaby.lame/video/7697307919943060767", > "title": null, > "description": "I guess is time to retire #learnfromkhaby #comedy 🥊", > "author": { > "id": "127905465618821121", > "name": "Khabane lame", > "handle": "khaby.lame", > "url": "https://www.tiktok.com/@khaby.lame", > "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…", > "isVerified": true > }, > "publishedAt": "2026-10-16T16:46:21.000Z", > "durationSeconds": 9, > "views": 5900000, > "likes": 339300, > "comments": 8538, > "thumbnailUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oQbHQmFfa5VY3NlkEGDAQT00RzqAqBOETlEafj~tplv-tiktokx-ori…", > "hashtags": [ > "learnfromkhaby", > "comedy" > ], > "type": "video", > "mentions": [], > "imageUrls": [], > "shares": 33800, > "saves": 17934, > "audioId": "7697308007327730462", > "audioTitle": "original sound", > "audioArtist": "Khabane lame", > "audioIsOriginal": true, > "isAd": false, > "isAiGenerated": false > } > ], > "videosCursor": "1781017260242:7649410784241405214" > } > ``` ## tiktok-hashtag A TikTok hashtag page. * **Example page:** [https://www.tiktok.com/tag/booktok](https://www.tiktok.com/tag/booktok) * **Returns:** A list of videos: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7223827494913215786", > "url": "https://www.tiktok.com/@jenna_bushhager/video/7223827494913215786", > "title": null, > "description": "#WorldBookDay is 4/23, and I've joined the #BookTok community to share our favorite books with you all! Duet to share…", > "author": { > "id": "6915876645917082629", > "name": "Jenna Bush Hager", > "handle": "jenna_bushhager", > "url": "https://www.tiktok.com/@jenna_bushhager", > "avatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0707efff51851e19e5e88f36bd87a298~tplv-tiktokx-cropcen…", > "isVerified": true > }, > "publishedAt": "2023-04-19T18:20:30.000Z", > "durationSeconds": 82, > "views": 39200, > "likes": 998, > "comments": 34, > "thumbnailUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ce0ee016ff8a483e8271ed4b4faebb3a~tplv-tiktokx-origin.ima…", > "hashtags": [ > "worldbookday", > "booktok", > "passthebook" > ], > "type": "video", > "mentions": [], > "imageUrls": [], > "shares": 36, > "saves": 134, > "audioId": "7223827501163006766", > "audioTitle": "original sound", > "audioArtist": "Jenna Bush Hager", > "audioIsOriginal": true, > "isAd": false, > "isAiGenerated": false > } > ], > "cursor": "seen_913912c8-cf6c-4cf4-b00f-7e95f9525571", > "page": null, > "total": null > } > ``` ## tiktok-sound A TikTok sound page that ends in the sound id. * **Example page:** [https://www.tiktok.com/music/original-sound-7652012548169976607](https://www.tiktok.com/music/original-sound-7652012548169976607) * **Returns:** A list of videos: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7652012587009215774", > "url": "https://www.tiktok.com/@khaby.lame/video/7652012587009215774", > "title": null, > "description": "Bro…. Where is the rest of my rice? 🍚🤨#learnfromkhaby #comedy ", > "author": { > "id": "127905465618821121", > "name": "Khabane lame", > "handle": "khaby.lame", > "url": "https://www.tiktok.com/@khaby.lame", > "avatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…", > "isVerified": true > }, > "publishedAt": "2026-06-16T15:17:17.000Z", > "durationSeconds": 30, > "views": 77400000, > "likes": 3500000, > "comments": 52800, > "thumbnailUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMCUBOFruAxeDj4qAILfYaqGVewvlQtIIIC0xI~tplv-tiktokx-ori…", > "hashtags": [ > "learnfromkhaby", > "comedy" > ], > "type": "video", > "mentions": [], > "imageUrls": [], > "shares": 305800, > "saves": 154390, > "audioId": "7652012548169976607", > "audioTitle": "original sound", > "audioArtist": "Khabane lame", > "audioIsOriginal": true, > "isAd": false, > "isAiGenerated": false > } > ], > "cursor": "seen_62f0083f-2789-4e1b-b88a-52aa4400f7d3", > "page": null, > "total": null, > "sound": { > "audioId": "7652012548169976607", > "audioTitle": "original sound", > "audioArtist": "Khabane lame", > "audioIsOriginal": true, > "videos": 411 > } > } > ``` ## tiktok-search A TikTok user search page (/search/user) or video search page (/search) with a q query. * **Example page:** [https://www.tiktok.com/search/user?q=street%20food](https://www.tiktok.com/search/user?q=street%20food) * **Returns:** A list of profiles: `results`, `cursor`, `page`, `total`. * **Options:** `sort` (TikTok's Sort by, for videos. Leave out for Relevance), `datePosted` (TikTok's Date posted, for videos. Leave out for All time), `cursor` (The cursor from the previous response. Send it as is), `query`, `type`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7329614299667727392", > "url": "https://www.tiktok.com/@streetfoodies33", > "handle": "streetfoodies33", > "name": "street food", > "bio": "Street food humour abonne-toi et explore une gastronomie unique et savoureuse 🌍", > "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/4ea0a8bbd98dc054cb6afcd80f4467a7~tplv-tiktokx-cropcenter:1…", > "isVerified": false, > "followers": 113300, > "following": null, > "posts": null, > "website": null, > "location": null, > "category": null, > "likes": 924514 > } > ], > "cursor": "seen_7b2e4f1c-90dc-4640-a041-6bdd616a5310", > "page": null, > "total": null > } > ``` ## tiktok-followers A TikTok profile page. * **Example page:** [https://www.tiktok.com/@khaby.lame](https://www.tiktok.com/@khaby.lame) * **Returns:** A list of profiles: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "7343882690238399494", > "url": "https://www.tiktok.com/@fatih.ged", > "handle": "fatih.ged", > "name": "Fatih Ged", > "bio": "صعدوا حسابي", > "avatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/02f1a89794af18c2c21b297dfe7ecd8b~tplv-tiktokx-cropcenter:10…", > "isVerified": false, > "followers": 434, > "following": 1707, > "posts": 124, > "website": null, > "location": null, > "category": null, > "likes": 1476, > "isPrivate": false, > "isOrganization": false, > "language": null, > "createdAt": null > } > ], > "cursor": "1793833913", > "page": null, > "total": null > } > ``` ## tiktok-following A TikTok profile page. * **Example page:** [https://www.tiktok.com/@khaby.lame](https://www.tiktok.com/@khaby.lame) * **Returns:** A list of profiles: `results`, `cursor`, `page`, `total`. * **Options:** `cursor` (The cursor from the previous response. Send it as is). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "id": "6769661547985847302", > "url": "https://www.tiktok.com/@xeviuniverse", > "handle": "xeviuniverse", > "name": "Xevi", > "bio": "Email: name@example.com\nPodcast ⬇️", > "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5f78661ab7569a41cae5e990d2316eee~tplv-tiktokx-cropcen…", > "isVerified": false, > "followers": 5336663, > "following": 245, > "posts": 1165, > "website": null, > "location": null, > "category": null, > "likes": 241600649, > "isPrivate": false, > "isOrganization": false, > "language": null, > "createdAt": null > } > ], > "cursor": "1659875581", > "page": null, > "total": null > } > ``` ## instagram-transcript An Instagram reel or video post. * **Example page:** [https://www.instagram.com/reel/DfS8Xbng4MD/](https://www.instagram.com/reel/DfS8Xbng4MD/) * **Returns:** `startSeconds`, `endSeconds`, `text`. * **Options:** `language` (BCP 47 language tag, e.g. en or pt-BR. Any case is accepted), `includeTimestamps`. * **Price:** 1 credit plus 1 credit for every 30 seconds of audio, up to 5 minutes. > [accordion] Example response > > ```json theme={null} > { > "videoId": "DfS8Xbng4MD", > "videoUrl": "https://www.instagram.com/reel/DfS8Xbng4MD/", > "language": "en", > "isAutoGenerated": true, > "durationSeconds": 10.9879375, > "transcribedSeconds": 11, > "text": "For more information visit www.fema.gov" > } > ``` # Search and the web Source: https://docs.stophy.dev/sources/web Read Google Scholar, Google Patents and Google Trends as JSON, and pull the email addresses and phone numbers from any public web page. Each parser reads one kind of page and returns the site's own data. Send the page's URL to [scrape](/api-reference/endpoint/scrape) with a `json` format that names the parser. The data comes back in `data.json`. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/scrape \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://scholar.google.com/scholar?q=attention+is+all+you+need","formats":[{"type":"json","parser":"google-scholar"}]}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://scholar.google.com/scholar?q=attention+is+all+you+need", formats: [{ type: "json", parser: "google-scholar" }], }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/scrape", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "url": "https://scholar.google.com/scholar?q=attention+is+all+you+need", "formats": [{"type": "json", "parser": "google-scholar"}], }, ) print(response.json()) ``` Send a parser's options in the same format, like `{"type": "json", "parser": "google-scholar", "options": {...}}`. See [Parsers](/guides/parsers) for how they work. | Parser | Reads | Price | | - | - | - | | [`google-scholar`](#google-scholar) | A Google Scholar results page with a search in q or a cites id. | 1 credit per call. | | [`google-patents`](#google-patents) | A Google Patents search page with q, inventor or assignee. | 1 credit per call. | | [`google-trends`](#google-trends) | A Google Trends explore page with search terms in q, or the trending now page. | 1 credit per call. | | [`emails`](#emails) | Any public web page. | 1 credit per call. | | [`phone-numbers`](#phone-numbers) | Any public web page. | 1 credit per call. | ## google-scholar A Google Scholar results page with a search in q or a cites id. * **Example page:** [https://scholar.google.com/scholar?q=attention+is+all+you+need](https://scholar.google.com/scholar?q=attention+is+all+you+need) * **Returns:** `title`, `url`, `format`, `authors`, `publication`, `year`. * **Options:** `citesId` (A result's citesId: lists the works that cite it, like Scholar's Cited by), `yearFrom` (Scholar's own Custom range: from this year), `yearTo` (Scholar's own Custom range: up to this year), `sort` (Scholar's own sort. Newest lists recent additions first), `type` (Scholar's own Any type, Review articles, or Case law), `includePatents`, `includeCitations` (Scholar's own include citations: works known only from citations), `page` (Page number, starting at 1). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "title": "Attention is all you need", > "url": "https://proceedings.neurips.cc/paper_files/paper/7181-attention-is", > "format": "pdf", > "authors": [ > "A Vaswani", > "N Shazeer", > "N Parmar" > ], > "publication": "Advances in neural …", > "year": 2017, > "publisher": "proceedings.neurips.cc", > "snippet": "… to attend to all positions in the decoder up to and including that position. We need to prevent … We implement this…", > "citations": 279946, > "citesId": "2960712678066186980", > "versions": 26, > "pdfUrl": "https://proceedings.neurips.cc/paper_files/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf?src_trk=em66c5166…", > "position": 1 > } > ], > "page": 1 > } > ``` ## google-patents A Google Patents search page with q, inventor or assignee. * **Example page:** [https://patents.google.com/?q=solid+state+battery\&assignee=Toyota](https://patents.google.com/?q=solid+state+battery\&assignee=Toyota) * **Returns:** `patentId`, `title`, `snippet`, `assignee`, `inventor`, `priorityDate`. * **Options:** `inventor`, `office` (Google Patents' own Patent office, like US, EP, WO, CN or JP), `language`, `dateType` (Which date before and after compare: Google Patents' own date choice), `after`, `before`, `status`, `type`, `litigation` (Google Patents' own Litigation: has related litigation, or no known), `sort`, `page` (Page number, starting at 1). * **Price:** 1 credit per call. Works without an API key. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "patentId": "US11018374B2", > "title": "All-solid-state battery", > "snippet": "5. The all-solid-state battery according to claim 1 , wherein, when the total volume of the anode layer is determined…", > "assignee": "Toyota Jidosha Kabushiki Kaisha", > "inventor": "Satoshi Mizutani", > "priorityDate": "2018-04-03", > "filingDate": "2019-03-14", > "grantDate": "2021-05-25", > "publicationDate": "2021-05-25", > "language": "en", > "patentUrl": "https://patents.google.com/patent/US11018374B2/en", > "pdfUrl": "https://patentimages.storage.googleapis.com/a9/f6/23/69fb5afe31ad17/US11018374.pdf", > "thumbnailUrl": "https://patentimages.storage.googleapis.com/d1/48/46/5134db0b904d57/US11018374-20210525-D00000.png", > "position": 1 > } > ], > "page": 1 > } > ``` ## google-trends A Google Trends explore page with search terms in q, or the trending now page. One term gives its related searches and several terms give their interest over time. Set options.view to related, interest or regions to pick that answer for the terms. * **Example page:** [https://trends.google.com/trends/explore?q=bitcoin\&geo=US\&date=today%2012-m](https://trends.google.com/trends/explore?q=bitcoin\&geo=US\&date=today%2012-m) * **Returns:** `query`, `value`. * **Options:** `searchType` (Google Trends' own search type: web, images, news, shopping or youtube), `category` (Google Trends' own top-level category), `resolution`, `country` (ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted), `time` (Google Trends' own Trending now time range), `status` (Google Trends' own Trend status: all, or only trends still rising), `sort` (Google Trends' own sort). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "results": [ > { > "query": "bitcoin price", > "value": 100 > } > ], > "rising": [ > { > "query": "spcx", > "increasePercent": null, > "isBreakout": true > } > ] > } > ``` ## emails Any public web page. * **Example page:** [https://www.hetzner.com/legal/legal-notice/](https://www.hetzner.com/legal/legal-notice/) * **Returns:** `email`, `pages`. * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "url": "https://www.hetzner.com/legal/legal-notice/", > "emails": [ > { > "email": "name@example.com", > "pages": [ > "https://www.hetzner.com/legal/legal-notice/", > "https://www.hetzner.com/unternehmen/ueber-uns/" > ] > } > ] > } > ``` ## phone-numbers Any public web page. * **Example page:** [https://www.hetzner.com/legal/legal-notice/](https://www.hetzner.com/legal/legal-notice/) * **Returns:** `phone`, `pages`. * **Options:** `country` (Two-letter country code for numbers written without a country prefix, such as DE. Without it the country comes from the page: its numbers with a prefix, its address and its domain ending). * **Price:** 1 credit per call. > [accordion] Example response > > ```json theme={null} > { > "url": "https://www.hetzner.com/legal/legal-notice/", > "phones": [ > { > "phone": "+1 555 0100", > "pages": [ > "https://www.hetzner.com/legal/legal-notice/", > "https://www.hetzner.com/support/", > "https://www.hetzner.com/unternehmen/ueber-uns/" > ] > } > ] > } > ```