# POST /v1/search

Run one search query and get the parsed SERP back — ranked items, not raw HTML.

**Credits:** 1 credit at the default depth (10 results); 10 credits at depth=100.

**Timeout:** 180s

## Parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | yes | — | Search query text. Required, max 700 chars. |
| `engine` | string | no | "google" | Search engine. Optional, default "google". One of: bing, google. |
| `location` | any | no | 2840 | Google Ads geotarget ID, an ISO country code (e.g. "US"), or a country name. Optional, default 2840 (United States). Look one up with /v1/locations. |
| `language` | string | no | "en" | ISO language code. Optional, default "en". |
| `device` | string | no | "desktop" | One of: desktop, mobile. Optional, default "desktop". |
| `depth` | integer | no | 10 | up to 10 results — 1 credit (default); up to 100 results — 10 credits. Bing returns up to 50 at depth=100. |

## Request

```http
POST /v1/search HTTP/1.1
Authorization: Bearer sof_live_your_key_here
Content-Type: application/json

{
  "query": "best running shoes"
}
```

## Response

Wrapped in the standard envelope (id, request_id, object, created_at, elapsed_ms, credits) -- documented once on The Contract. The body below is an example response with this endpoint's `data` shape; values vary per request, and a `…` marks an array cut short for display.

```json
{
  "id": "srch_7f34stnlffnsbalonq66dpuj",
  "request_id": "req_7e5465ge5fjmziqx5dyueaqyvy",
  "object": "search",
  "created_at": "2026-07-29T12:00:00Z",
  "elapsed_ms": 244,
  "credits": {
    "charged": 1,
    "balance": 9857
  },
  "data": {
    "query": "best running shoes",
    "engine": "google",
    "location": 2840,
    "language": "en",
    "device": "desktop",
    "total_results": 84900000,
    "serp_url": "https://www.google.com/search?q=best+running+shoes",
    "result_types": [
      "organic"
    ],
    "results_count": 10,
    "items": [
      {
        "type": "organic",
        "rank": 1,
        "page": 1,
        "domain": "example.com",
        "title": "The 12 Best Running Shoes",
        "url": "https://example.com/best-running-shoes",
        "description": "Our team tested 40 pairs...",
        "displayed_link": "example.com › reviews › shoes",
        "date": null,
        "site_name": "Example Running Co.",
        "rating": {
          "value": 4.6,
          "votes": 1284,
          "max": 5
        },
        "sitelinks": [
          {
            "title": "Best Trail Running Shoes",
            "url": "https://example.com/best-running-shoes/trail",
            "description": null
          },
          {
            "title": "Best Budget Running Shoes",
            "url": "https://example.com/best-running-shoes/budget",
            "description": null
          }
        ],
        "price": null,
        "highlighted_words": [
          "running shoes"
        ]
      }
    ]
  }
}
```

## Response fields

What each field in `data` (above) means.

| Field | Description |
| --- | --- |
| `data.query` | The query string you sent. |
| `data.engine` | Search engine that served this result set. |
| `data.location` | Google Ads geotarget ID this call ran against. |
| `data.language` | ISO language code this call ran against. |
| `data.device` | Device profile this search ran as. |
| `data.total_results` | The search engine's own on-page estimate for the query, not the number of items here. null when the page shows none (most modern result pages), and can be 0 beside real results when the engine says so. |
| `data.serp_url` | URL of the search-results page that was fetched, or null if the engine didn't report one. |
| `data.result_types` | Distinct SERP item types observed on the page. |
| `data.results_count` | Number of entries in items. |
| `data.items` | One parsed result per SERP item. Not sorted by rank: rank counts within each item's type. |
| `data.items[].type` | Item type. Each type has its own field set; see the per-type tables below. |
| `data.items[].rank` | 1-based position among results of the same type -- for organic results, the rank you track. Single-instance blocks (AI overview, featured snippet, People Also Ask) are always 1. |
| `data.items[].page` | Present on organic and paid items only -- other item types carry a different field set (see the per-type tables below). Results page number this item was found on (1 for the first page). |
| `data.items[].domain` | Registrable domain hosting the result. |
| `data.items[].title` | Result title. |
| `data.items[].url` | Result URL. |
| `data.items[].description` | Result description/snippet text, or null if the result carries none. |
| `data.items[].displayed_link` | The line shown under the title -- usually the page's path (site › section › page), sometimes a comment count or age. |
| `data.items[].date` | Date text as the results page displayed it (e.g. "Jan 6, 2020", localised), or null. |
| `data.items[].site_name` | Publisher or site name shown next to the result, if the SERP surfaced one; null otherwise. |
| `data.items[].rating` | Star rating block ({value, votes, max}), or null if the result carries no rating. |
| `data.items[].sitelinks` | Sub-links shown under the result; empty array if none. |
| `data.items[].price` | Price block ({amount, currency, displayed}), or null if the result carries no price. |
| `data.items[].highlighted_words` | Query terms the engine bolded in the snippet; empty array if none were highlighted. |

## SERP item fields

`data.items[]` holds a different field set per item's `type`. One table below per type.

`featured_snippet`, `images`, `top_stories`, and `shopping` currently return only `type` and `rank`.

### `ai_overview`

| Field | Description |
| --- | --- |
| `type` | Always "ai_overview". |
| `rank` | 1-based position among ai_overview items; a SERP carries one such block, so this is 1. |
| `is_async` | True when the engine loaded the AI Overview asynchronously; false when it rendered with the rest of the page. |
| `items` | The overview's text blocks, in order. |
| `items[].title` | Block heading, or null. |
| `items[].text` | Block body text, or null. |
| `items[].images` | Image URLs shown in this block; empty when none. |
| `items[].references` | Sources cited by this block; empty when none. |
| `items[].references[].source` | Citation label as the engine displayed it, or null. |
| `items[].references[].domain` | Registrable domain of the cited page. |
| `items[].references[].url` | URL of the cited page. |
| `items[].references[].title` | Cited page's title, or null. |
| `items[].references[].text` | Excerpt the engine quoted from the cited page, or null. |
| `references` | Every source cited anywhere in the overview, flattened across all blocks; empty when none. |
| `references[].source` | Citation label as the engine displayed it, or null. |
| `references[].domain` | Registrable domain of the cited page. |
| `references[].url` | URL of the cited page. |
| `references[].title` | Cited page's title, or null. |
| `references[].text` | Excerpt the engine quoted from the cited page, or null. |

### `knowledge_graph`

| Field | Description |
| --- | --- |
| `type` | Always "knowledge_graph". |
| `rank` | 1-based position among knowledge_graph items; a SERP normally carries one panel, so this is normally 1. |
| `title` | Subject name, or null. |
| `subtitle` | Short descriptor under the title, e.g. a role or category, or null. |
| `description` | Longer description text, or null. |
| `url` | Link to the subject's own site, or null. |
| `image_url` | Photo URL, or null. |
| `logo_url` | Logo URL, or null. |
| `attributes` | Extra label/value facts about the subject (e.g. founding date, headquarters); empty when none. |

### `local_pack`

| Field | Description |
| --- | --- |
| `type` | Always "local_pack". |
| `rank` | 1-based position among local results. |
| `title` | Business name, or null. |
| `description` | Short description text, or null. |
| `category` | Business category, e.g. "Running store", or null. |
| `address` | Street address as shown, or null. |
| `domain` | Registrable domain of the business's own site, or null. |
| `phone` | Phone number as shown, or null. |
| `url` | Link to the business's own site, or null. |
| `is_paid` | True if this is a paid placement. |
| `rating` | Star rating block ({value, votes, max}), or null if the result carries no rating. |
| `price` | Price block ({amount, currency, displayed}), or null if the result carries no price. |
| `latitude` | Latitude, or null. |
| `longitude` | Longitude, or null. |

### `organic`

| Field | Description |
| --- | --- |
| `type` | Always "organic". |
| `rank` | 1-based position among organic results -- the rank you track. |
| `page` | Results page number this item was found on (1 for the first page). |
| `domain` | Registrable domain hosting the result. |
| `title` | Result title. |
| `url` | Result URL. |
| `description` | Result description/snippet text, or null if the result carries none. |
| `displayed_link` | The line shown under the title -- usually the page's path (site › section › page), sometimes a comment count or age. |
| `date` | Date text as the results page displayed it (e.g. "Jan 6, 2020", localised), or null. |
| `site_name` | Publisher or site name shown next to the result, if the SERP surfaced one; null otherwise. |
| `rating` | Star rating block ({value, votes, max}), or null if the result carries no rating. |
| `sitelinks` | Sub-links shown under the result; empty array if none. |
| `price` | Price block ({amount, currency, displayed}), or null if the result carries no price. |
| `highlighted_words` | Query terms the engine bolded in the snippet; empty array if none were highlighted. |

### `paid`

| Field | Description |
| --- | --- |
| `type` | Always "paid". |
| `rank` | 1-based position among paid (ad) results. |
| `page` | Results page number this item was found on (1 for the first page). |
| `domain` | Registrable domain hosting the result. |
| `title` | Result title. |
| `url` | Result URL. |
| `description` | Result description/snippet text, or null if the result carries none. |
| `displayed_link` | The line shown under the title -- usually the page's path (site › section › page), sometimes a comment count or age. |
| `date` | Date text as the results page displayed it (e.g. "Jan 6, 2020", localised), or null. |
| `site_name` | Publisher or site name shown next to the result, if the SERP surfaced one; null otherwise. |
| `rating` | Star rating block ({value, votes, max}), or null if the result carries no rating. |
| `sitelinks` | Sub-links shown under the result; empty array if none. |
| `price` | Price block ({amount, currency, displayed}), or null if the result carries no price. |
| `highlighted_words` | Query terms the engine bolded in the snippet; empty array if none were highlighted. |

### `people_also_ask`

| Field | Description |
| --- | --- |
| `type` | Always "people_also_ask". |
| `rank` | 1-based position among people_also_ask items; a SERP carries one such block, so this is 1. |
| `items` | The questions the engine surfaced, in order. |
| `items[].question` | The question text. |
| `items[].seed_question` | Question this one was inserted as a follow-up to, or null if it appeared without one. |
| `items[].answers` | This question's answer; an empty array unless the results page shipped the answer already expanded. |
| `items[].answers[].featured_title` | Headline text shown above the answer body, or null. |
| `items[].answers[].title` | The answer's title, or null. |
| `items[].answers[].url` | Link to the answer's source page, or null. |
| `items[].answers[].domain` | Registrable domain of the answer's source page, or null. |
| `items[].answers[].description` | The answer body text, or null. |
| `items[].answers[].date` | Date text as shown, or null. |
| `items[].answers[].images` | Image URLs shown in the answer; empty when none. |
| `items[].answers[].table` | Table block shown in the answer ({header, rows}), or null when the answer carries no table. |
| `items[].answers[].table.header` | Column headers, as text. |
| `items[].answers[].table.rows` | Table rows; each entry is a list of cell text for that row. |

### `related_searches`

| Field | Description |
| --- | --- |
| `type` | Always "related_searches". |
| `rank` | 1-based position among related_searches items; a SERP carries one such block, so this is 1. |
| `items` | Suggested follow-up queries, as plain text. |

### `video`

| Field | Description |
| --- | --- |
| `type` | Always "video". |
| `rank` | 1-based position among video items; a SERP normally carries one video block, so this is normally 1. |
| `items` | The videos in this block, in order. |
| `items[].title` | Video title, or null. |
| `items[].source` | Source line as shown, e.g. view count and age, or null. |
| `items[].url` | Video URL, or null. |
| `items[].date` | Upload/publish date as text, when the SERP shows one; null otherwise. |