# Plainserp documentation

> Plainserp is a Google search API for AI agents. It returns Google's organic results as JSON for $0.30 per 1,000 searches, can return page text as Markdown, and comes with an MCP server and an agent skill. It is an independent service and is not affiliated with Google.

This file is the complete Plainserp documentation in Markdown, for AI tools and agents. The web version is at https://plainserp.com/docs. Last updated 2026-10-07.

## Key facts

- Search endpoint: `GET https://plainserp.com/v1/search?q=...` with the header `Authorization: Bearer <key>`. Keys start with `ps_live_`.
- Price: $0.0003 per search, which is $0.30 per 1,000, at any volume. There are no plans or monthly fees.
- Free tier: a new account starts with $0.30, enough for 1,000 searches. No card is needed.
- Results: up to 20 per page and up to 6 pages per query, so the first 120 results. Filters for country (`gl`), language (`hl`), recency (`time`) and safe search (`safe`).
- Page reading: add `read=1` to `read=5` to a search, or call `GET https://plainserp.com/v1/read?url=...`. Returns Markdown, up to 15,000 characters per page. $0.0025 per page read ($2.50 per 1,000), charged only when the page is returned.
- Left out on purpose: AI Overviews, People also ask, knowledge panels, ads, and image and video packs. Results are organic only.
- Failed requests are never charged.
- Rate limit: 300 searches a minute per account by default. It can be raised on request.
- MCP server: `https://plainserp.com/mcp` (Streamable HTTP, Bearer key), with the tools `web_search` and `read_page`.
- Payment: prepaid balance, topped up in cryptocurrency from $6. The balance doesn't expire.
- Typical speed: a search returns in about one to two and a half seconds.

## Quickstart

1. Create an account at https://plainserp.com/signup and make an API key at https://plainserp.com/dashboard/keys.
2. Save the key in the `PLAINSERP_KEY` environment variable.
3. Make a request.

```bash
curl "https://plainserp.com/v1/search?q=postgres+connection+pooling&num=3" \
  -H "Authorization: Bearer $PLAINSERP_KEY"
```

Response:

```json
{
  "query": "postgres connection pooling",
  "results": [
    {
      "position": 1,
      "title": "PgBouncer - lightweight connection pooler for PostgreSQL",
      "url": "https://www.pgbouncer.org/",
      "snippet": "PgBouncer keeps a pool of server connections and hands them to clients…"
    },
    {
      "position": 2,
      "title": "PostgreSQL: Documentation: Connections and Authentication",
      "url": "https://www.postgresql.org/docs/current/runtime-config-connection.html",
      "snippet": "max_connections determines the maximum number of concurrent connections…"
    },
    {
      "position": 3,
      "title": "pgpool Wiki",
      "url": "https://www.pgpool.net/",
      "snippet": "Pgpool-II is a middleware that works between PostgreSQL servers and clients…"
    }
  ],
  "cost_usd": 0.0003
}
```

## Authentication

Send the key as a Bearer token in the `Authorization` header. Keys start with `ps_live_`. Keep keys on a server: anyone who has a key can spend the account's balance. A leaked key can be revoked in the dashboard.

```
Authorization: Bearer $PLAINSERP_KEY
```

## Search

`GET /v1/search` runs one Google search and returns the organic results. Every request is a GET over HTTPS and every response is JSON.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| q | string | Required | The search query. |
| num | integer | 10 | How many results per page, from 1 to 20. |
| pages | integer | 1 | How many pages to fetch, from 1 to 6. Each page is one search. |
| page | integer | 1 | Which page to start from, from 1 to 6. |
| read | integer | 0 | Also return the full text of this many top results, from 0 to 5. |
| gl | string | None | Two-letter country code to search from, such as us or de. |
| hl | string | en | Language code for the results, such as en or fr. |
| time | string | None | Only results from the past day, week, month or year. |
| safe | string | off | Safe search level: off, medium or high. |

## Response

A successful call returns status 200 with this shape.

| Field | Type | Description |
| --- | --- | --- |
| query | string | The query you sent. |
| results | array | The organic results, in Google's order. |
| results[].position | integer | Rank across all pages, starting at 1. |
| results[].title | string | The page title. |
| results[].url | string | The page address. |
| results[].snippet | string | The text Google shows under the title. |
| results[].thumbnail | string | An image address. Only present when Google has one. |
| results[].content | string | The page's text as Markdown. Only on results you asked to read. |
| results[].read_error | string | Why a page couldn't be read. That page isn't charged. |
| cost_usd | number | What the call cost, in US dollars: each page of results plus each page read. |

## Pagination

Google returns results in pages of up to 20 and goes 6 pages deep, which is the first 120 results of a query. Set `pages` to fetch several pages in one call; they come back as one list, in order. Each page is charged as one search. If a page fails it isn't charged and the pages that worked are returned. To fetch a single deeper page, set `page`, for example `page=4`.

```bash
# Pages 1 to 3: results 1 to 60, charged as three searches
curl "https://plainserp.com/v1/search?q=postgres+connection+pooling&num=20&pages=3" \
  -H "Authorization: Bearer $PLAINSERP_KEY"
```

## Reading pages

Search results come with a short snippet. Plainserp can also fetch a page and return its main text as Markdown, with menus, ads and scripts removed.

Add `read` to a search to get the text of the top results in the same call. Each one gains a `content` field.

```bash
curl "https://plainserp.com/v1/search?q=postgres+connection+pooling&num=5&read=2" \
  -H "Authorization: Bearer $PLAINSERP_KEY"
```

Or read any single address with `GET /v1/read`.

```bash
curl "https://plainserp.com/v1/read?url=https://www.pgbouncer.org/" \
  -H "Authorization: Bearer $PLAINSERP_KEY"
```

```json
{
  "url": "https://www.pgbouncer.org/",
  "title": "PgBouncer - lightweight connection pooler for PostgreSQL",
  "content": "# PgBouncer\n\nLightweight connection pooler for PostgreSQL…",
  "cost_usd": 0.0025
}
```

- Reading a page costs $0.0025, which is $2.50 per 1,000 pages, on top of the search.
- A page that can't be read isn't charged. In a search it comes back with a `read_error` and its snippet; `/v1/read` returns a `read_failed` error.
- Text is cut off at 15,000 characters.
- Reading adds a few seconds, because the pages are fetched while you wait.
- Pages that build their content with scripts, sit behind a login, or block automated visitors may not be readable. Video and social sites are skipped.

## Errors

Errors use standard HTTP status codes and a JSON body with a `code` to match on. A request that returns an error is never charged.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | invalid_request | A parameter is missing or out of range. |
| 401 | invalid_api_key | The key is missing, wrong or revoked. |
| 402 | insufficient_balance | Your balance is too low. Top up to continue. |
| 429 | rate_limited | You passed your per-minute limit. Wait for Retry-After, then retry. |
| 502 | upstream_error | Google didn't return results. Retry the request. |
| 502 | read_failed | The page couldn't be loaded or had no readable text. |

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low. Top up to continue."
  }
}
```

For 429, wait for the number of seconds in the `Retry-After` header. For 502, wait a second or two and try again, doubling the wait after each failed attempt.

## Rate limits

Each account can make 300 searches a minute by default. The count resets at the start of every clock minute, and a call that fetches several pages counts once per page. Every response carries the limit and what is left. Past the limit the API returns 429 with a `Retry-After` header. To ask for a higher limit, message @vvz25 on Telegram.

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
Retry-After: 23
```

## Pricing and billing

| What | Price | Per 1,000 |
| --- | --- | --- |
| One page of search results (up to 20 results) | $0.0003 | $0.30 |
| One page read as Markdown | $0.0025 | $2.50 |
| A request that fails | $0 | $0 |

- A search costs the same whatever `num` is. `pages=3` is three searches.
- New accounts start with $0.30, which covers 1,000 searches. No card is needed.
- Money is added in advance, from $6, in cryptocurrency. The balance doesn't expire. There are no plans or monthly fees.
- Every response includes `cost_usd`.

## Use with agents

Most agent frameworks take a tool definition and a function to run when the model calls it. This definition works with any model that supports tool use.

```json
{
  "name": "web_search",
  "description": "Search Google. Returns titles, URLs and snippets.",
  "input_schema": {
    "type": "object",
    "properties": {
      "q": { "type": "string", "description": "The search query" },
      "num": { "type": "integer", "description": "Results to return, 1 to 20" }
    },
    "required": ["q"]
  }
}
```

```python
import os, requests

def web_search(q: str, num: int = 10) -> list[dict]:
    r = requests.get(
        "https://plainserp.com/v1/search",
        params={"q": q, "num": num},
        headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["results"]
```

Asking for 5 to 10 results is usually enough for a model to pick what to read, and it keeps the tool result short.

## MCP server

To give an AI client search without writing code, connect it to the Plainserp MCP server. It uses the same API key and balance as any other call.

| Setting | Value |
| --- | --- |
| URL | https://plainserp.com/mcp |
| Transport | Streamable HTTP |
| Header | Authorization: Bearer YOUR_KEY |
| Tools | web_search (q, num, pages, gl, hl, time, read) and read_page (url) |

```bash
claude mcp add --transport http plainserp https://plainserp.com/mcp \
  --header "Authorization: Bearer $PLAINSERP_KEY"
```

```json
{
  "mcpServers": {
    "plainserp": {
      "type": "http",
      "url": "https://plainserp.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}
```

## Agent skill

A skill is a short instruction file that teaches a coding agent how to use something. The Plainserp skill is at https://plainserp.com/skill/plainserp-search/SKILL.md.

```bash
mkdir -p ~/.claude/skills/plainserp-search
curl -o ~/.claude/skills/plainserp-search/SKILL.md \
  https://plainserp.com/skill/plainserp-search/SKILL.md
```

## What it doesn't do

- It returns organic results only. AI Overviews, People also ask, knowledge panels, ads and image or video packs are left out.
- It reaches the first 120 results of a query and no further.
- It has no browser, so pages that need scripts to show their content can't be read.
- Plainserp is an independent service and isn't affiliated with Google. A change on Google's side can cause a short outage, and failed requests are never charged.

## Use cases

### AI agents

Agents search far more than people do. They need results they can read in one pass, at a price that doesn't make every lookup a budget decision. Page: https://plainserp.com/use-cases/ai-agents

1. **Hand the model a tool.** Use the tool definition from the docs, or connect the MCP server and write no code at all.
2. **Run the search when it asks.** One GET request returns titles, links and snippets as JSON.
3. **Let it choose what to read.** The model picks the promising links and fetches those pages with its own tools.

Connect an agent with MCP:

```bash
claude mcp add --transport http plainserp https://plainserp.com/mcp \
  --header "Authorization: Bearer $PLAINSERP_KEY"
```

Why it fits:

- Results are plain JSON with no boxes to strip out, so tool results stay short.
- An MCP server and a skill file are ready to use.
- Failed searches cost nothing, so retries are free.

Know before you start:

- It returns links and snippets. Your agent still needs a way to open pages.
- There are no AI Overviews or answer boxes. The model writes its own answer.

Cost example: An agent that makes 2,000 searches a day is 2,000 searches a day, which costs $0.60 a day.

### RAG and grounding

A model's knowledge stops at its training date and your vector store only holds what you put in it. A web search at question time fills the gap. Page: https://plainserp.com/use-cases/rag

1. **Search with the user's question.** Send it as it is, or have the model rewrite it into a few queries first.
2. **Use the snippets, or fetch the pages.** Snippets are often enough for a quick answer. Fetch the top links when you need depth.
3. **Answer with sources.** Pass the text to the model with its URLs, so every claim can carry a link.

Build context from the top results:

```python
import os, requests

def web_context(question: str, n: int = 8) -> str:
    r = requests.get(
        "https://plainserp.com/v1/search",
        params={"q": question, "num": n},
        headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
        timeout=30,
    )
    r.raise_for_status()
    return "\n\n".join(
        f"[{hit['position']}] {hit['title']}\n{hit['url']}\n{hit['snippet']}"
        for hit in r.json()["results"]
    )
```

Why it fits:

- Every result has a position, title, URL and snippet, ready to cite.
- The time filter keeps answers about recent events recent.
- Country and language settings give local results for local questions.

Know before you start:

- Snippets are a sentence or two. For full passages, fetch the pages yourself.
- Most calls take one to two and a half seconds, which adds to your answer time.

Cost example: An app that answers 10,000 questions a day with one search each is 10,000 searches a day, which costs $3.00 a day.

### SEO rank tracking

Each result comes back with its position, and one call can cover the first 120 results. That is most of what a rank tracker needs. Page: https://plainserp.com/use-cases/rank-tracking

1. **List your keywords.** Add the country and language each one should be checked in.
2. **Fetch the pages you care about.** Set pages to 6 to get the first 120 results in one call.
3. **Find your domain.** Look for your site in the list and store its position with the date.

Find a domain's position for a keyword:

```python
import os, requests
from urllib.parse import urlparse

def rank(keyword: str, domain: str, country: str = "us") -> int | None:
    r = requests.get(
        "https://plainserp.com/v1/search",
        params={"q": keyword, "num": 20, "pages": 6, "gl": country},
        headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
        timeout=60,
    )
    r.raise_for_status()
    for hit in r.json()["results"]:
        if urlparse(hit["url"]).netloc.endswith(domain):
            return hit["position"]
    return None  # not in the first 120
```

Why it fits:

- Positions run from 1 to 120 across pages, so there is nothing to work out.
- Country and language are set per request.
- The same price at any volume makes large keyword lists affordable.

Know before you start:

- Positions can differ a little from what a browser shows, because results come from Google's search-box service and are not personalised.
- Only organic results are returned. Ads, map packs and featured snippets are not tracked.
- Checking thousands of keywords in a burst can pass the default limit of 300 searches a minute. Ask for a higher one.

Cost example: Checking 500 keywords a day to 120 results deep is 3,000 searches a day, which costs $0.90 a day.

### Brand and news monitoring

Search for your name on a schedule with the time filter set to the past day, and you get a feed of pages that are new. Page: https://plainserp.com/use-cases/brand-monitoring

1. **Choose what to watch.** Your brand, your product names, your competitors, or a phrase in quotes.
2. **Search on a schedule.** Set time to day so each run only returns recent pages.
3. **Keep what's new.** Compare links against the ones you have already seen and alert on the rest.

New mentions from the past day:

```python
import os, requests

seen: set[str] = set()  # load this from wherever you store it

def new_mentions(term: str) -> list[dict]:
    r = requests.get(
        "https://plainserp.com/v1/search",
        params={"q": f'"{term}"', "num": 20, "time": "day"},
        headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
        timeout=30,
    )
    r.raise_for_status()
    fresh = [hit for hit in r.json()["results"] if hit["url"] not in seen]
    seen.update(hit["url"] for hit in fresh)
    return fresh
```

Why it fits:

- The time filter narrows results to the past day, week, month or year.
- Search operators such as quotes, site: and minus work as they do on Google.
- A check every hour costs very little.

Know before you start:

- It finds pages Google has indexed. Social posts and pages behind logins mostly won't appear.
- There is no push alert. You run the searches and decide what counts as new.

Cost example: Watching 50 terms once an hour is 1,200 searches a day, which costs $0.36 a day.

### Lead and company research

Turn a spreadsheet of company names into websites, profile links and contact pages by running one search per row. Page: https://plainserp.com/use-cases/lead-generation

1. **Start from your list.** Company names, optionally with a city or industry to avoid mix-ups.
2. **Search for what's missing.** The official site, a careers page, or a profile on a site you name with site:.
3. **Take the top result.** Store the link, and flag rows where the match looks doubtful for a person to check.

Find each company's website:

```python
import csv, os, requests

def top_link(query: str) -> str | None:
    r = requests.get(
        "https://plainserp.com/v1/search",
        params={"q": query, "num": 3},
        headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
        timeout=30,
    )
    r.raise_for_status()
    hits = r.json()["results"]
    return hits[0]["url"] if hits else None

with open("companies.csv") as f:
    for row in csv.DictReader(f):
        print(row["name"], top_link(f'{row["name"]} official website'))
```

Why it fits:

- One search per row keeps the cost of a whole list to a few dollars.
- Asking for only a few results keeps responses small and quick.
- site: searches target one directory or network at a time.

Know before you start:

- The top result is a good guess, not a verified match. Check the important ones.
- It returns public pages only. It doesn't find emails or phone numbers for you.
- Follow the privacy and marketing laws that apply to how you use the contacts.

Cost example: Looking up 5,000 companies once is 5,000 searches a run, which costs $1.50 a run.

### Market and competitor research

Run the searches your customers run, count which sites appear, and you have a picture of who is winning attention in your market. Page: https://plainserp.com/use-cases/market-research

1. **Collect the searches that matter.** Product categories, problems people describe, comparisons between brands.
2. **Fetch the results for each.** Go as deep as you need, in each country you sell in.
3. **Count the domains.** Rank sites by how often and how high they appear. Repeat monthly to see movement.

Which sites appear most for a set of searches:

```python
import os, requests
from collections import Counter
from urllib.parse import urlparse

def share_of_results(queries: list[str], country: str = "us") -> Counter:
    seen = Counter()
    for q in queries:
        r = requests.get(
            "https://plainserp.com/v1/search",
            params={"q": q, "num": 20, "gl": country},
            headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
            timeout=30,
        )
        r.raise_for_status()
        seen.update(urlparse(hit["url"]).netloc for hit in r.json()["results"])
    return seen

print(share_of_results(["best crm for startups", "crm pricing comparison"]).most_common(10))
```

Why it fits:

- Clean lists of links are easy to count, compare and chart.
- Country and language settings show how a market differs by region.
- Low cost makes it practical to repeat the same study every month.

Know before you start:

- It shows who appears in organic results, not how much traffic they get.
- Ads and shopping results are left out, so paid competition isn't visible.

Cost example: A monthly study of 1,000 searches in 3 countries is 3,000 searches a month, which costs $0.90 a month.

### No-code automations

Anything that can make a web request can use Plainserp. That covers Zapier, Make, n8n, Google Apps Script and most internal tools. Page: https://plainserp.com/use-cases/automations

1. **Add a web request step.** Most tools call it HTTP request or Webhooks.
2. **Point it at the search address.** Use GET, put your query in q, and add your key as an Authorization header.
3. **Use the results in the next step.** Each result arrives as its own item with a title, link and snippet.

What to enter in the request step:

```
Method:   GET
URL:      https://plainserp.com/v1/search
Query:    q    = {{ the text to search for }}
          num  = 5
Header:   Authorization = Bearer YOUR_KEY
```

Why it fits:

- One GET request with a header is all there is to set up.
- Results are a simple list, which automation tools can loop over directly.
- Small workflows cost cents a month.

Know before you start:

- There isn't a ready-made Plainserp app in these tools. You use their generic web request step.
- Keep your key in the tool's secret or credential store, not in a shared step.

Cost example: A workflow that searches 100 times a day is 3,000 searches a month, which costs $0.90 a month.

### Research and datasets

Researchers and evaluation teams need large sets of queries with their results. A flat price and plain JSON make that a script, not a project. Page: https://plainserp.com/use-cases/research-datasets

1. **Prepare your queries.** A file with one query per line, plus any country or language you want to vary.
2. **Fetch and save.** Write each response to disk as it arrives, so a stopped run can pick up where it left off.
3. **Stay under your limit.** Pace requests to your per-minute limit, or ask for a higher one for a big run.

Save results for a file of queries:

```python
import json, os, time, requests

with open("queries.txt") as f, open("results.jsonl", "a") as out:
    for q in map(str.strip, f):
        r = requests.get(
            "https://plainserp.com/v1/search",
            params={"q": q, "num": 20},
            headers={"Authorization": f"Bearer {os.environ['PLAINSERP_KEY']}"},
            timeout=30,
        )
        if r.status_code == 429:  # over the per-minute limit
            time.sleep(int(r.headers.get("Retry-After", 5)))
            continue
        if r.ok:
            out.write(json.dumps(r.json()) + "\n")
```

Why it fits:

- The price doesn't change with volume, so a budget is easy to state up front.
- Failed requests aren't charged, so reruns only pay for what's missing.
- Rate-limit headers tell your script exactly when to slow down.

Know before you start:

- Results change over time. Record the date with each one.
- Each query reaches 120 results at most.
- Check that your use of the collected results fits the terms and laws that apply to you.

Cost example: Collecting results for 100,000 queries is 100,000 searches a run, which costs $30.00 a run.

## Frequently asked questions

### What is Plainserp?

Plainserp is a Google search API built for AI agents. You send a query and get Google's organic results back as JSON: position, title, URL and snippet. It costs $0.30 per 1,000 searches with no plan, and your first 1,000 searches are free.

### Is this Google's official API?

No. Plainserp is an independent service and isn't affiliated with Google. It fetches public Google results and returns them as JSON. That also means an occasional outage is possible when Google changes something, and you are never charged for a request that fails.

### Why is it so cheap?

It only does one thing. There is no browser rendering, no AI Overview extraction and no screenshotting, so each query costs very little to serve. The price is the same whether you buy a thousand queries or ten million.

### What do I get back?

Up to 20 organic results per call, each with a position, title, URL and snippet. Ask for several pages at once to get up to the first 120 results of a query.

### What don't I get?

AI Overviews, People also ask, knowledge panels, ads and the other boxes Google puts around the results. If your agent needs those, this isn't the right API. Pages that only show their content after running scripts, or that sit behind a login, usually can't be read.

### How fast is it?

Most calls come back in one to two and a half seconds. It's built to be cheap and dependable for agents, and it isn't the fastest option on the market.

### Can it read the pages too?

Yes. Add read to a search and the top results come back with their full text as Markdown, or read any single address directly. Each page read costs $0.0025, which is $2.50 per 1,000, and pages that can't be loaded aren't charged.

### Can my AI client use it without code?

Yes. There is an MCP server at plainserp.com/mcp that gives any compatible client a web_search tool, and a skill file that teaches coding agents how to add search to your project. Both are in the docs.

### Is there a rate limit?

Each account can make 300 searches a minute by default. Your dashboard shows the limit and how much of it you're using, and you can ask for more.

### Is there a monthly plan or a minimum?

No plan. You add money from $6 and each search takes $0.0003 from it. Your first 1,000 searches are free.

## Support and legal

- Support: message @vvz25 on Telegram (https://t.me/vvz25) with the email on the account.
- Terms of service: https://plainserp.com/terms
- Privacy policy: https://plainserp.com/privacy
- Refund policy: https://plainserp.com/refunds
