Understanding results

A served search answers this shape, from the Playground and from GET /v1/query alike:

{
  "id": "qry_bbadb104fad74005a996dcd379a072cb",
  "target": "google_search",
  "query": "serp api",
  "geo": "us",
  "locale": "en-us",
  "page": 1,
  "results": {
    "organic": [
      {
        "position": 1,
        "title": "Search engine results page - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Search_engine_results_page",
        "domain": "wikipedia.org",
        "snippet": "A search engine results page (SERP) is a webpage that is displayed by a search engine in response to a query by a user."
      }
    ]
  }
}

query is the text as it was run, after surrounding whitespace was trimmed and runs of whitespace collapsed. locale is the resolved value, so it is filled in even when you sent none.

The five organic fields

Every entry in results.organic has exactly these fields.

Field	Meaning
position	1-based rank within the answered page, after duplicate URLs are removed.
title	The result’s title as the engine showed it.
url	The destination URL.
domain	The registrable domain of url (example.co.uk), or the hostname when it has no public suffix.
snippet	The engine’s description text. Empty when the engine gave none.

results.organic can be empty when the engine returned nothing for the query. That is still a served search and still costs a credit.

What a search costs

Every served search costs one credit, which X-Credits-Used on the response reports. Failed fetches are charged too (502 upstream_error, 504 upstream_timeout) because the search was run; a 500 internal_error is not charged, and neither is a request that failed validation.

Credits come out of your plan’s quota, and the X-Quota-Limit, X-Quota-Used and X-Quota-Remaining headers on the same response say where you stand. X-Quota-Reset joins them on a paid plan, whose quota runs on the plan’s billing cycle; the 100 free trial requests never reset, so they have no reset header. X-Credits-Balance reports your credit balance — the credits bought in a pack, spent only after the quota is gone and never expiring. With the quota spent and that balance at zero, searches answer 402 quota_exceeded. Pricing and quotas explains the period and how to buy a pack.