Search API Responses

The JSON response of a successful PacketStream search, the result fields of each request type, rich web blocks, Markdown output, headers, and the free account endpoint.

A successful search returns HTTP 200 with a JSON body:

{
  "request_id": "6f1c2b9e-3d4a-4f7b-9c1e-2a5b8d0e7f13",
  "search": {
    "engine": "google",
    "type": "search",
    "query": "coffee grinders",
    "country": "us",
    "page": 1
  },
  "results": [
    {
      "position": 1,
      "title": "The Best Coffee Grinders of 2026",
      "url": "https://www.example.com/coffee-grinders",
      "snippet": "We tested 20 burr and blade grinders for consistency and noise.",
      "displayed_url": "https://www.example.com › reviews › coffee-grinders"
    }
  ],
  "people_also_ask": [{ "question": "Are burr grinders worth it?" }],
  "related_searches": [
    {
      "query": "best burr coffee grinder",
      "url": "https://www.google.com/search?q=best+burr+coffee+grinder"
    }
  ],
  "result_count": 1,
  "charged_units": 1,
  "balance_remaining_usd": 12.3456,
  "processing_time_ms": 2140
}

Top-level fields

Field	Description
`request_id`	Unique request ID, also sent as the `X-Request-Id` header. Quote it when you contact support.
`search`	The accepted request after normalization. `engine`, `type`, `query`, `country`, and `page` are always present. `language`, `location`, `device`, `time_range`, `safe_search`, `google_domain`, and `autocorrect` appear when you sent them. `uule` is never echoed.
`results`	The result list for the type, possibly empty. Absent for `ai_mode`.
Rich blocks	For `type=search`, any of the web search blocks that Google showed.
`ai_mode`	For `type=ai_mode`, the answer’s `text_blocks` and `references`.
`result_count`	Items in `results`. For `ai_mode`, the number of references, which can be `0`.
`charged_units`	Searches billed for this response: always `1`.
`balance_remaining_usd`	Your balance after this search, rounded down to four decimals. May be omitted.
`processing_time_ms`	Server processing time in milliseconds.

Responses may gain new optional fields and blocks over time. Ignore fields you do not recognize.

Result items by type

Every item has a 1-based position. Optional fields are left out when Google does not provide them. All URLs are absolute http or https URLs: tracking redirects, relative links, and inline data are never returned.

Type	Items per page	Item fields
`search`	Up to 10	`title`, `url`, `snippet`, and when available `displayed_url`, `favicon_url`, `date` (as displayed), and `sitelinks` (up to 6, each with `title`, `url`, and an optional `snippet`).
`news`	Up to 10	`title`, `url`, `source`, `date` (ISO 8601 as given, or empty), and an optional `thumbnail_url`.
`shopping`	Up to 100	`title`, `price` (as displayed), `source` (the merchant), and when available `extracted_price`, `old_price`, `rating`, `reviews`, `delivery`, `tag`, and `product_id`.
`places`	Up to 10	`title`, `place_id`, and when available `address`, `rating`, `reviews`, `type`, `types`, `phone`, `website`, `latitude`, `longitude`, `price`, and `open_state`.
`autocomplete`	Up to 10	`suggestion` and an optional `relevance`.
`scholar`	Up to 10	`title`, `url`, `snippet`, `publication` (authors, venue, and year), and when available `cited_by` and `pdf_url`.
`ai_mode`	One answer	No `results` list. The `ai_mode` block has `text_blocks` and `references`, and `result_count` is the number of references.

rating is a number from 0 to 5, and reviews is an integer.

Web search blocks

type=search can include these blocks next to results. A block appears only when Google showed it and it could be read reliably, and mobile searches carry fewer blocks. Do not build logic that requires a block to be present.

Block	Shape
`ai_overview`	Google’s AI overview: up to 40 `text_blocks`, each with a `type` of `paragraph` or `heading` and its `text`, or `list` and its `items`. Up to 20 `references`, each with `title`, `url`, and `source`.
`knowledge_graph`	The knowledge panel: `title`, optional `description` and `source` (`name` and an optional `url`), up to 30 `attributes` (`name` and `value`), and up to 10 `profiles` (`name` and `url`).
`people_also_ask`	Up to 10 related questions, each `{"question": "…"}`.
`local_results`	Up to 10 map-pack places: `position`, `title`, and when available `place_id`, `rating`, `reviews`, `type`, `address`, `hours`, and `price_range`.
`ads`	Up to 10 text ads: `position`, `block_position` (`top` or `bottom`), `title`, `displayed_url`, and an optional `snippet`. Click-tracking links are never returned.
`related_searches`	Up to 10 related queries, each with `query` and its Google `url`.
`search_information`	When available, `total_results` (an integer), `showing_results_for` (the corrected query), and `original_query_spelling_fixed`.

type=ai_mode returns an ai_mode block with the same shape as ai_overview, and no results list. Each text value in these blocks is at most 2,000 bytes.

Google sometimes gives an AI answer without sources. Its references is then an empty array, and an ai_mode response has result_count: 0. The search is still billed.

Markdown format

Set "format": "markdown" to get text/markdown; charset=utf-8 instead of JSON. The output starts with a heading that names the query, lists the results as numbered links with their snippets, then adds any AI overview or AI Mode answer, knowledge panel, places, related questions, and related searches.

Text from web pages is escaped, so the output never contains raw HTML or injected links. The format suits language-model prompts. Errors are always JSON, and batch items can only use JSON.

Headers

Header	Sent with	Meaning
`X-Request-Id`	Every `/v1/` response, including errors	The request ID.
`X-RateLimit-Limit`	Search, batch, fetch, and MCP `tools/call` responses	The key’s burst size, `10`.
`X-RateLimit-Remaining`	The same responses	Requests left in the burst. Approximate, because limits are tracked on each API server.
`Retry-After`	`429` responses	Seconds to wait: `1`.
`Allow`	`405` responses	The methods the path accepts.

Account

GET /v1/account returns your balance, the price, and your usage counts. It is free and does not use a rate-limit token.

curl -s https://api.packetstream.io/v1/account \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY"

{
  "request_id": "2c9d4e1a-7b3f-4a8e-b5c6-1d0e9f8a7b6c",
  "account": {
    "balance_usd": 12.3456,
    "price_per_1000_usd": 2.5,
    "searches_today": 42,
    "searches_last_30_days": 1830,
    "fetches_today": 7,
    "fetches_last_30_days": 120
  },
  "rate_limit": { "requests_per_second": 5, "burst": 10 }
}

Counts cover accepted requests and use UTC days.
Search counts include every request type and leave out fetches. fetches_today and fetches_last_30_days count accepted fetch requests.
rate_limit is the nominal limit for each key.