> 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",
            "outline": [
                "Providers: Providers of GPAI models that have been placed on the market before this date need to be compliant with the AI Act by 2 August 2027. ... Member States: Deadline for Member States to report to the Commission on the status of the financial and human resources of the national competent ..."
            ],
            "url": "https://artificialintelligenceact.eu/implementation-timeline/",
            "metadata": {
                "position": 1
            }
        },
        {
            "title": "EU AI Act Timeline: Key Compliance Dates & Deadlines Explained",
            "outline": [
                "While the EU Commission is working with member states to build out the reporting and monitoring infrastructure of the AI Act until August 2025, companies have several key areas to focus on: establishing a risk management system, implementing data governance measures, drawing up technical ..."
            ],
            "url": "https://www.dataguard.com/eu-ai-act/timeline",
            "metadata": {
                "position": 2
            }
        },
        {
            "title": "Timeline for the Implementation of the EU AI Act | AI Act Service Desk",
            "outline": [
                "The EU’s AI Act legislation applies progressively, with a full roll-out of the main application milestones foreseen by 2 August 2028."
            ],
            "url": "https://ai-act-service-desk.ec.europa.eu/en/ai-act/timeline/timeline-implementation-eu-ai-act",
            "metadata": {
                "position": 3
            }
        }
    ],
    "related_questions": [],
    "related_searches": [],
    "params": {
        "query": "eu ai act compliance deadlines",
        "location": "DE",
        "max_results": 3
    },
    "metadata": {
        "timestamp": 1791289627,
        "request_id": "1791289625962078444"
    }
}
```

{% hint style="warning" %}
**`outline`** 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 width="404.04296875">Description</th><th width="95.94140625">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[].outline[]</code></td><td>SERP result snippets. Truncated mid-sentence.</td><td>array of strings</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.