> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/web-api/search.md).

# /search

Learn how to use Oxylabs Web API /search endpoint to search the live web and collect ranked results.

The `/v1/search` endpoint performs live web searches and returns ranked organic results, including titles, snippets, URLs, position metadata, and related queries. It works as a discovery tool to identify authoritative web pages before passing target URLs to the [`/v1/scrape`](/products/web-api/scrape.md) endpoint for full-page extraction.

## Request sample

The endpoint accepts a JSON request body with the search **query**, **result limits**, and **geo-location** parameters.

```bash
curl https://webapi.oxylabs.io/v1/search \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "eu ai act compliance deadlines",
    "max_results": 3,
    "location": "DE"
  }'
```

### Request parameters

<table><thead><tr><th width="123">Parameter</th><th width="533">Description</th><th width="88">Type</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>query</code></mark></td><td>Search keyword or phrase (between <code>1</code> and <code>2,048</code> characters).</td><td>string</td></tr><tr><td><code>max_results</code></td><td>Number of organic search results to return (between <code>1</code> and <code>20</code>). Default: <code>10</code></td><td>integer</td></tr><tr><td><code>location</code></td><td>ISO 3166-1 alpha-2 country code (e.g. <code>DE</code>, <code>US</code>) for localized search.</td><td>string</td></tr></tbody></table>

&#x20;    – mandatory parameter.

{% hint style="warning" %}
Unknown or misspelled parameters are rejected with an HTTP `400 Bad Request` status code, not ignored.
{% endhint %}

### Request optimization

<details>

<summary><strong><code>query</code></strong></summary>

It's recommended to write what a person would type into a search box. Keyword-shaped queries outperform sentence-shaped ones:

<table><thead><tr><th width="373">Instead of</th><th>Use</th></tr></thead><tbody><tr><td>"Can you tell me what the compliance deadlines for the EU AI Act are?"</td><td><code>eu ai act compliance deadlines</code></td></tr><tr><td>"I want to know how much Figma costs per seat"</td><td><code>figma pricing per seat</code></td></tr></tbody></table>

One question per request. A compound query returns results that match neither half well.

</details>

<details>

<summary><strong><code>max_results</code></strong></summary>

Parameter is a limit, not a target. A query with fewer matches returns fewer results, which are ordered best-first.

</details>

<details>

<summary><strong><code>location</code></strong></summary>

Pricing, availability, language and rankings often shift by country.

ISO 3166-1 alpha-2 code is the only accepted format (e.g. `DE`, `US`). A well-formed pair that isn't an assigned country is rejected with a `400` error code. Omitting the the parameter sets a `default` locale, which is optimal only when the answer is not location-sensitive.

</details>

## Output sample

```json
{
  "state": "done",
  "results": [
    {
      "title": "Implementation Timeline | EU Artificial Intelligence Act",
      "short_description": "Date 2 August 2025 Providers: need to be compliant with the AI Act by 2 August 2027. Date 2 August 2025 (and every year thereafter) Commission: Deadline for ...",
      "url": "https://artificialintelligenceact.eu/implementation-timeline/",
      "metadata": { "position": 1 }
    },
    {
      "title": "EU AI Act Timeline: Key Compliance Deadlines for 2027-2028",
      "short_description": "The EU AI Act has crossed the line from theory to operating reality...",
      "url": "https://policy-insider.ai/eu-ai-act-timeline-key-compliance-deadlines-for-2027-2028/",
      "metadata": { "position": 2 }
    }
  ],
  "related_questions": [],
  "related_searches": [
    { "query": "ai act timeline" }
  ],
  "params": {
    "query": "eu ai act compliance deadlines",
    "location": null,
    "max_results": 3
  },
  "metadata": {
    "timestamp": 1787431568,
    "request_id": "1788875675880097469"
  }
}
```

{% hint style="warning" %}
**`short_description`** is just a representative snippet. To get live data from the page itself, [scrape the URL](/products/web-api/scrape.md).
{% endhint %}

### Output dictionary

<table><thead><tr><th width="244">Field</th><th>Description</th><th width="81">Type</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>"done"</code> on success. A search that encounters an upstream failure returns <code>500</code> with <code>state: "faulted"</code> (see <a href="/products/web-api/troubleshooting.md">Error codes</a>).</td><td>string</td></tr><tr><td><code>results</code></td><td>Ranked organic results, best first. Always present, so empty output means nothing matched.</td><td>array</td></tr><tr><td><code>results[].title</code></td><td>Fetched page title.</td><td>string</td></tr><tr><td><code>results[].short_description</code></td><td>SERP result snippet. Truncated mid-sentence.</td><td>string</td></tr><tr><td><code>results[].url</code></td><td>Absolute URL of the result. Pass to <a href="/products/web-api/scrape.md"><code>/v1/scrape</code></a>.</td><td>string</td></tr><tr><td><code>results[].metadata.position</code></td><td>Organic SERP position, starting at <code>1</code>.</td><td>integer</td></tr><tr><td><code>related_questions</code></td><td>"People also ask" question object containing <code>question</code>, <code>title</code>, and <code>snippet</code> (when available).</td><td>array</td></tr><tr><td><code>related_searches</code></td><td>Related search queries, each containing <code>query</code>.</td><td>array</td></tr><tr><td><code>params</code></td><td>Execution parameters including defaults.</td><td>object</td></tr><tr><td><code>metadata.timestamp</code></td><td>Unix timestamp in seconds.</td><td>integer</td></tr><tr><td><code>metadata.request_id</code></td><td>19-digit request handle. <strong>Include in support tickets.</strong></td><td>string</td></tr></tbody></table>

{% hint style="info" %}
`related_searches` is useful for query expansion when a first search comes back thin. It offers the phrasing that has more coverage behind it.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/web-api/search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.