# 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: google, google-maps, google-news, google-images, google-shopping, bing, yandex, youtube. |
| `location` | any | no | 2840 | Google Ads geotarget ID. 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 | 10 results — 1 credit (default); 100 results — 10 credits. |

## 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, object, created_at, elapsed_ms, cache, credits) -- documented once on The Contract. The body below is a real envelope with this endpoint's `data` shape; values vary per request, and a `…` marks an array cut short for display.

```json
{
  "id": "srch_tnq5objwpmflh2poczbwxnfr",
  "request_id": "req_c7leybmgtzholcwoyhozbqsqkq",
  "object": "search",
  "created_at": "2026-08-08T16:50:38Z",
  "elapsed_ms": 142,
  "cache": "miss",
  "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": [
          {
            "type": "sitelink",
            "title": "Best Trail Running Shoes",
            "description": null,
            "url": "https://example.com/best-running-shoes/trail"
          },
          {
            "type": "sitelink",
            "title": "Best Budget Running Shoes",
            "description": null,
            "url": "https://example.com/best-running-shoes/budget"
          }
        ],
        "price": null
      }
    ]
  }
}
```

## 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 the search was simulated from. |
| `data.total_results` | The search engine's own total-results estimate for the query -- not the number of items in this response. |
| `data.serp_url` | URL of the search-results page that was fetched. |
| `data.result_types` | Distinct SERP item types observed on the page. Only "organic" is populated today. |
| `data.results_count` | Number of entries in items. |
| `data.items` | One parsed result per SERP item, in rank order. |
| `data.items[].type` | Item type. Only "organic" is populated today. |
| `data.items[].rank` | 1-based rank on the results page. |
| `data.items[].page` | 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. |
| `data.items[].displayed_link` | Breadcrumb-style path shown under the title. |
| `data.items[].date` | Result date, if the SERP surfaced one; null otherwise. |
| `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[].sitelinks[].type` | Sitelink type, e.g. "sitelink". |
| `data.items[].sitelinks[].title` | Sitelink title. |
| `data.items[].sitelinks[].url` | Sitelink URL. |
| `data.items[].sitelinks[].description` | Sitelink description, or null if the SERP didn't include one. |
| `data.items[].price` | Price block ({current, currency, displayed}), or null if the result carries no price. |