Polyscrape
Start free
polyscrape API · Search

Search

Search the web and get every result back as scraped Markdown.

Runs a web search for a keyword and country locale and returns the top organic results — each one already scraped to clean Markdown, not just a link and a snippet. Built for agents that need to READ pages, not just collect URLs. Priced at $0.001 for the search plus $0.002 per returned result, so a 3-result search is $0.007 and a 10-result search is $0.021; you are only charged for the results actually returned. Results are cached and served for up to 30 days (there is no freshness parameter): a cached search is reused when it was originally fetched with at least as many results as you request. A no-match query returns an empty results array and is charged $0.001 (the search only), but an unsupported country returns 400 and a failed search returns 502 — neither is charged. An uncached search can take up to 90 seconds. Ideal for giving an AI agent real web search, research, and competitive content analysis.

POST /api/v1/search $0.001 + $0.002 / result
Get API Key Open Playground

Use your polyscrape API key instantly, or inspect the sample response first.

curl 
curl -X POST https://polyscrape.com/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $POLYSCRAPE_API_KEY" \
  -d '{"country": "us", "keyword": "seo tools", "limit": 3}'

Sample response

{
  "country": "us",
  "keyword": "seo tools",
  "results": [
    {
      "description": "You need effective SEO tools which are 100% free? Check out our Search Engine Optimization tools.",
      "markdown": "# Small SEO Tools\n\n## Text Analysis Tools\n\nA complete set of text tools is now at your fingertips...",
      "position": 1,
      "title": "100% Free SEO Tools - SmallSEOTools.com",
      "url": "https://smallseotools.com/"
    }
  ]
}

API Playground

Run a real /api/v1/search request. No key? We show the real sample result so you can still inspect the shape.

Endpoint

POST /api/v1/search

sample mode
Auth header X-API-Key
Cost $0.001 + $0.002 / result

Leave empty to inspect the response shape without spending API balance.

Sample mode: explore the real response shape for free. Add a key to run a live request.

Response

POST /api/v1/search

sample 
{
  "country": "us",
  "keyword": "seo tools",
  "results": [
    {
      "description": "You need effective SEO tools which are 100% free? Check out our Search Engine Optimization tools.",
      "markdown": "# Small SEO Tools\n\n## Text Analysis Tools\n\nA complete set of text tools is now at your fingertips...",
      "position": 1,
      "title": "100% Free SEO Tools - SmallSEOTools.com",
      "url": "https://smallseotools.com/"
    }
  ]
}

Request and response

The full contract for /api/v1/search: what to send and what comes back.

Request body

keyword string required

The search query.

country string optional

Two-letter locale for the search (50 codes supported). Default "us".

limit integer optional

How many results (1–10) to return, each with page Markdown. Default 3.

Response fields

Field Type Description
keyword string The searched keyword, echoed back.
country string The locale used for the search.
results object[] Search results, top-ranked first.
results[].position integer Rank of the result (1-based).
results[].url string Result page URL.
results[].title string Result page title.
results[].description string Result page meta description.
results[].markdown string Full scraped Markdown of the result page.

Code examples

Copy, paste, swap in your API key.

curl -X POST https://polyscrape.com/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: " \
  -d '{"country": "us", "keyword": "seo tools", "limit": 3}'

What developers build with it

Common ways Search ends up in production.

Giving an AI agent web search with readable page content.

Research and content discovery.

Competitive content analysis.

Status codes

The same predictable contract on every endpoint.

200 Success. The lookup completed and was charged, even if the response is empty (a no-match search, or a thin page).
400 The request was rejected before any fetch (for search: an unsupported country code). Never charged.
401 Missing or unknown API key. Never charged.
402 Not enough balance on the account. Never charged. The detail is a JSON object with error, message, credits_required, and api_credits.
422 Invalid request body (wrong shape or types). The detail is a list of per-field errors. Never charged.
429 Rate limit exceeded: max 10 requests per second per API key (5/second for parse, which is CPU-heavier). Never charged.
502 Upstream fetch failed — the target page or search could not be fetched (site down, unreachable, timed out, or blocked). Never charged.
Body Every error response is JSON shaped as {"detail": ...}. detail is a message string, except 402 (a JSON object) and 422 (a list of field errors).

Other endpoints

Explore the rest of the polyscrape API.

Scrape

/api/v1/scrape

Parse

/api/v1/parse

Account Balance

/api/v1/account/balance

View all endpoints

Pay once. Spend when needed.

New accounts start with a free API balance. Paid balance never expires, so it can sit until your workflows need it.

Free

$0.50 to start

$0.50 free balance to start. Get an API key in seconds with no credit card.

  • Scrape, Search, and Parse
  • No credit card required
  • Perfect for a first integration
Create free account
Starter

$10 one-time

Adds $10 to your API balance for steady production traffic and early automated jobs.

  • Balance never expires
  • From $0.001 per call
  • Useful for small pipelines
Get started
Pro Most popular

$100 one-time

$130 spendable balance, including a $30 bonus. The sweet spot for production workloads.

  • $100 + $30 free balance
  • Best value per workload
  • Built for automated pipelines
Get started
FAQ

Questions before you connect?

Pricing & Balance

Usage-based, charged against your prepaid balance. Scrape and parse cost $0.001 per 1,000 words of Markdown returned (minimum $0.001, capped at $0.10). Search costs $0.001 for the search plus $0.002 per result returned. Same prices across REST and MCP — no quota math, no tiers.
The whole scraping stack, handled for you: a residential proxy, a real Chrome browser fingerprint, HTML-to-Markdown conversion, built-in document parsing (PDF, Word, PowerPoint, Excel, Outlook, EPUB, CSV, XML), and caching. You send a URL, a search, or a document and get back clean, LLM-ready Markdown.
No. Your API balance never expires, so you can use it whenever your workflows need it. In the unlikely event polyscrape is ever discontinued, unused paid balance is refunded.
Paid API requests stop with a 402 until you add more balance. This keeps spend predictable and prevents unexpected charges.

API & Integration

Create and manage API keys from your account, then send your key in the X-API-Key header from your app, scripts, or internal tools.
Yes. Your dashboard shows every request, its cost, and your remaining balance, so you can track spend while building and running automated workflows.
Yes, a completed request is billable even when the answer is empty (for example a page with no readable content). Errors like 402 or 429 are never charged.
We enforce a rate limit of 10 requests per second per API key. If you exceed it, the API returns HTTP 429. Build exponential backoff (briefly pausing before retrying) into your application code.
Our support team responds to email inquiries within 1 business day. We can help with account, billing, and API integration questions.

Give your product and agents clean Markdown.

Start with a free key and $0.50 free balance, on REST, MCP, or both.

Start with $0.50 free