# Get Google results as JSON or Markdown

> Send one HTTP request and get Google web, news, shopping, places, autocomplete, Scholar, or AI Mode results as JSON or Markdown, billed per successful search.

**Early beta.** Fields, limits, and availability may change during the beta. These pages describe what the API serves today. Questions or problems? [Contact support](https://packetstream.io/contact-us/).

The Search API runs a Google search and returns the results as JSON or Markdown. One endpoint covers web results, news, shopping, places, autocomplete, Google Scholar, and AI Mode.

The same API key works for the [Fetch API](https://packetstream.io/docs/fetch-api/), which reads a web page as Markdown, and for the [MCP server](https://packetstream.io/docs/mcp/), which gives AI agents both tools.

## Before you begin

You need:

- a [PacketStream account](https://app.packetstream.io/signup?account=buy&next=search_api) with funds in its balance. Searches draw from the same prepaid balance as proxy traffic;
- an API key. Create one on the [Search API page of the dashboard](https://app.packetstream.io/dashboard/search_api). The key is shown once, so copy it when it appears.

Load the key into your shell without writing it into the command history:

```bash
read -r -s -p 'PacketStream API key: ' PACKETSTREAM_API_KEY
printf '\n'
export PACKETSTREAM_API_KEY
```

## Make your first request

```bash
curl -s https://api.packetstream.io/v1/search \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "coffee grinders", "country": "us"}'
```

The response lists up to 10 web results, each with `position`, `title`, `url`, and `snippet`. It also includes any [rich blocks](https://packetstream.io/docs/search-api/responses/#web-search-blocks) Google showed, such as an AI overview. To search news, shopping, or another Google surface, set [`type`](https://packetstream.io/docs/search-api/parameters/#request-types).

### Python

```python
import os
import requests

response = requests.post(
    "https://api.packetstream.io/v1/search",
    headers={"Authorization": f"Bearer {os.environ['PACKETSTREAM_API_KEY']}"},
    json={"query": "coffee grinders", "type": "news"},
    timeout=35,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["position"], result["title"], result["url"])
```

### JavaScript

Run this on a server, never in a browser, so the key stays private.

```javascript
const response = await fetch("https://api.packetstream.io/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PACKETSTREAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "coffee grinders", type: "news" }),
  signal: AbortSignal.timeout(35_000),
});
const payload = await response.json();
if (!response.ok) throw new Error(`${payload.error.code}: ${payload.error.message}`);
console.log(payload.result_count, payload.results[0]);
```

The server finishes or gives up within 25 seconds, so use a client timeout of at least 35 seconds.

## Pricing

- Each successful search costs **$0.0025**, which is **$2.50 per 1,000**, for every request type and option.
- Failed requests are free: validation errors, rate limits, balance errors, and upstream failures. One rare exception is described under [billing](https://packetstream.io/docs/search-api/errors-limits/#billing).
- A successful search that finds no results is still billed, because the search ran.
- A search needs at least $0.0025 in your balance before it starts.

The dashboard shows daily usage and spend. [`GET /v1/account`](https://packetstream.io/docs/search-api/responses/#account) returns your balance and usage counts for free.

## Authentication

Send the key in an `Authorization: Bearer` header on every request. Keys start with `ps_`, followed by 64 hexadecimal characters.

- An account has one active key. It works for the Search API, the Fetch API, and the MCP server.
- Rotating the key on the dashboard revokes the old key immediately. Revoking it stops all API access until you create a new one.
- A missing, malformed, revoked, or unknown key returns `401 unauthorized`. The MCP server is the exception: it lists its tools without a key, and a tool call with a key problem returns an error result instead. See [MCP errors](https://packetstream.io/docs/mcp/reference/#errors).
- Keep the key out of URLs, source control, and code that runs in a browser. The API sends no CORS headers, so web pages cannot call it directly.

## Base URL and endpoints

Send every request over HTTPS to `https://api.packetstream.io`.

| Method | Path | Purpose | Billed |
| --- | --- | --- | --- |
| GET, POST | `/v1/search` | Run one search. See [parameters](https://packetstream.io/docs/search-api/parameters/). | Each accepted search |
| POST | `/v1/search/batch` | Run 1 to 10 searches in one request. See [batch searches](https://packetstream.io/docs/search-api/parameters/#batch-searches). | Each accepted item |
| GET | `/v1/account` | Read your balance, usage counts, price, and rate limit. See [account](https://packetstream.io/docs/search-api/responses/#account). | Free |
| POST | `/v1/fetch` | Read one web page as Markdown. See the [Fetch API](https://packetstream.io/docs/fetch-api/). | Each fetch that returns page content |
| POST | `/v1/mcp` | MCP server for AI agents. See [MCP](https://packetstream.io/docs/mcp/). | Each successful tool call |

`GET /v1/search` takes the same fields as query parameters. Prefer POST for sensitive queries: a GET puts the query in the URL, where proxies and logs along the way can record it.

## Privacy

For billing and support, the API records each request's ID, type, outcome, latency, and charge. It does not store your query text or the results.

Related pages:

- [Parameters & types](https://packetstream.io/docs/search-api/parameters/): Every request field, the request types and their options, and batch searches.
- [Responses](https://packetstream.io/docs/search-api/responses/): Result items, rich blocks, Markdown output, headers, and the account endpoint.
- [Errors & limits](https://packetstream.io/docs/search-api/errors-limits/): Error codes, billing rules, rate limits, and timeouts.
- [Use with AI agents](https://packetstream.io/docs/mcp/): Connect Claude Code, Codex, Cursor, and other MCP clients.