> 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/api-reference/pt-br/endpoints-principais.md).

# Endpoints principais

Referência para os dois endpoints principais da Web API, /search e /scrape — parâmetros, esquema de resposta e exemplos.

<table><thead><tr><th width="184">Endpoint</th><th>Retorna</th></tr></thead><tbody><tr><td><a href="#post-v1-search"><code>/search</code></a></td><td>Resultados orgânicos da web classificados</td></tr><tr><td><a href="#post-v1-scrape"><code>/scrape</code></a></td><td>Extrai conteúdo da URL</td></tr></tbody></table>

### `POST /v1/search`

Resultados orgânicos da web classificados.

**Modos:** `sync` only

#### **Esquema da requisição**

```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"}'
```

<table><thead><tr><th width="122">Parâmetro</th><th width="88.5">Tipo</th><th width="84.5">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>string</td><td>Sim</td><td>Frase de busca por palavra-chave. <code>1</code> até <code>2048</code> caracteres.</td></tr><tr><td><code>max_results</code></td><td>inteiro</td><td>Não</td><td>Número de resultados a retornar. <code>1</code>–<code>20</code>. Padrão <code>10</code></td></tr><tr><td><code>location</code></td><td>string</td><td>Não</td><td>Código de país ISO 3166-1 alpha-2, por exemplo <code>DE</code>. Padrão <code>nulo</code></td></tr></tbody></table>

#### **Resposta**

{% code expandable="true" %}

```json
{
  "state": "done",
  "results": [
    {
      "title": "Implementation Timeline | EU Artificial Intelligence Act",
      "outline": [
        "Date 2 August 2025 Providers: need to be compliant..."
      ],
      "url": "https://artificialintelligenceact.eu/implementation-timeline/",
      "metadata": {
        "position": 1
      }
    }
  ],
  "related_questions": [
    {
      "question": "When does the EU AI Act take effect?",
      "title": "Implementation Timeline | EU Artificial Intelligence Act",
      "snippet": "The Act applies in stages, beginning in August 2024."
    }
  ],
  "related_searches": [
    { "query": "ai act timeline" }
  ],
  "params": {
    "query": "eu ai act compliance deadlines",
    "location": "DE",
    "max_results": 3
  },
  "metadata": {
    "timestamp": 1787431568,
    "request_id": "1788875675880097469"
  }
}
```

{% endcode %}

<table><thead><tr><th width="265">Campo</th><th width="84">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>state</code></td><td>string</td><td><code>done</code>. <code>faulted</code> em um <code>500</code></td></tr><tr><td><code>results[]</code></td><td>array</td><td>Resultados orgânicos classificados, com os melhores primeiro. Vazio quando nada corresponder</td></tr><tr><td><code>results[].title</code></td><td>string</td><td>Título da página</td></tr><tr><td><code>results[].outline</code></td><td>array de strings</td><td>Trechos de conteúdo. Cada item é truncado</td></tr><tr><td><code>results[].url</code></td><td>string</td><td>URL absoluta do resultado</td></tr><tr><td><code>results[].metadata.position</code></td><td>inteiro</td><td>Posição, começando em <code>1</code></td></tr><tr><td><code>related_questions[]</code></td><td>array</td><td>Entradas de "As pessoas também perguntam". Omitido quando vazio</td></tr><tr><td><code>related_questions[].question</code></td><td>string</td><td>A pergunta. Sempre presente</td></tr><tr><td><code>related_questions[].title</code></td><td>string</td><td>Título da página de resposta <em>(Opcional)</em></td></tr><tr><td><code>related_questions[].snippet</code></td><td>string</td><td>Trecho que responde à pergunta. Truncado <em>(Opcional)</em></td></tr><tr><td><code>related_searches[]</code></td><td>array</td><td>Consultas relacionadas, cada uma com um <code>query</code>. Omitido quando vazio</td></tr><tr><td><code>params</code></td><td>objeto</td><td>Parâmetros usados na requisição, com os padrões preenchidos</td></tr><tr><td><code>metadata.timestamp</code></td><td>inteiro</td><td>timestamp Unix em segundos</td></tr><tr><td><code>metadata.request_id</code></td><td>string</td><td>Identificador da requisição</td></tr></tbody></table>

### `POST /v1/scrape`

Extrai dados da URL e retorna seu conteúdo nos formatos solicitados.

**Modos:** `sync`, `async`, `batch`

#### **Esquema da requisição**

```bash
curl https://webapi.oxylabs.io/v1/scrape \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"url": "https://artificialintelligenceact.eu/implementation-timeline/", "output": ["markdown"]}'
```

<table><thead><tr><th width="133">Parâmetro</th><th width="93">Tipo</th><th width="90">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>sim</td><td>Absoluta <code>http</code> ou <code>https</code> URL. Envie-a sem alterações, strings de consulta e segmentos de caminho são relevantes</td></tr><tr><td><code>output</code></td><td>array de strings</td><td>não</td><td>Formatos a retornar: <code>["html"]</code> (padrão), <code>["markdown"]</code>, <code>["json"]</code>, <code>["screenshot"]</code>.<br><code>json</code> retorna campos analisados (por meio de analisadores dedicados ou <a href="/products/web-api/scrape/ai-parsing.md">análise por IA</a>). <code>screenshot</code> requer <code>run_js: true</code></td></tr><tr><td><code>json</code></td><td>objeto</td><td>não</td><td>Obrigatório quando <code>output</code> inclui <code>json</code> (e nenhum analisador dedicado estiver disponível): <code>{"prompt": string}</code> ou <code>{"schema": object}</code>, nunca ambos</td></tr><tr><td><code>json.prompt</code></td><td>string</td><td>não</td><td>Instruções de extração em linguagem natural para <code>output: ["json"]</code>. <code>max_len: 8192</code>, padrão: <code>nulo</code>. Não pode ser usado com <code>json.schema</code>.</td></tr><tr><td><code>json.schema</code></td><td>objeto</td><td>não</td><td>Objeto OpenAPI / JSON Schema que define a estrutura JSON de saída obrigatória. <code>10</code> até <code>65535</code> caracteres, padrão: <code>nulo</code>. Não pode ser usado com <code>json.prompt</code></td></tr><tr><td><code>location</code></td><td>string</td><td>não</td><td>Código de país de duas letras para buscar, por exemplo <code>DE</code></td></tr><tr><td><code>device</code></td><td>string</td><td>não</td><td><code>desktop</code> (padrão) ou <code>mobile</code></td></tr><tr><td><code>run_js</code></td><td>booleano</td><td>não</td><td>Executa o JavaScript da página antes da captura. Mais lento, use um timeout do cliente de 150 segundos ou mais</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td><strong>Somente assíncrono.</strong> URL de webhook para o job concluído. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>objeto</td><td>não</td><td><strong>Somente assíncrono.</strong> Entrega o resultado em um bucket em vez da resposta: <code>{"type": string, "url": string}</code>. <code>tipo</code> é <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. <code>url</code> não é validado</td></tr></tbody></table>

{% hint style="warning" %}
Páginas com um **analisador dedicado** (por exemplo [páginas de produtos da Bed Bath & Beyond](/api-reference/pt-br/scrapers-dedicados/scrapers-de-comercio.md#post-v1-scrape-bedbathandbeyond-product)) são analisadas automaticamente e não precisam de `json` parâmetro com `prompt` ou `schema`. Incluí-los substitui os analisadores dedicados existentes.
{% endhint %}

#### **Resposta**

{% code expandable="true" %}

```json
{
  "state": "done",
  "results": [
    {
      "html": "107.175.25.67\n",
      "metadata": {
        "page": 1,
        "run_js": false,
        "url": "https://ip.oxylabs.io/",
        "statuses": {
          "http_request": {
            "code": 200,
            "tag": "HTTP_OK"
          }
        }
      }
    }
  ],
  "params": {
    "url": "https://ip.oxylabs.io",
    "output": ["html"],
    "json": { "schema": null, "prompt": null },
    "location": null,
    "device": "desktop",
    "run_js": null,
    "storage": {
      "type": "s3",
      "url": "oxylabs.test/7517848208047890433.json"
    },
    "callback_url": null,
    "client_notes": null
  },
  "metadata": {
    "timestamp": 1792394688,
    "request_id": "7517848208047890433",
    "statuses": {
      "storage_upload": {
        "code": 13000,
        "tag": "UPLOAD_SUCCESS"
      }
    }
  }
}
```

{% endcode %}

<table><thead><tr><th width="215">Campo</th><th width="81">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>state</code></td><td>string</td><td><code>done</code>, <code>pendente</code>, ou <code>faulted</code></td></tr><tr><td><code>status</code></td><td>inteiro</td><td>Presente em respostas de erro. Código de status HTTP</td></tr><tr><td><code>results[]</code></td><td>array</td><td>Uma entrada para a URL solicitada. Presente quando <code>state</code> é <code>done</code></td></tr><tr><td><code>results[].markdown</code></td><td>string</td><td>A página em Markdown. Presente quando solicitado</td></tr><tr><td><code>results[].html</code></td><td>string</td><td>A marcação bruta. Presente quando solicitado</td></tr><tr><td><code>results[].json</code></td><td>objeto</td><td>Campos analisados. Presente quando solicitado</td></tr><tr><td><code>results[].screenshot</code></td><td>string</td><td>A captura de tela. Presente quando solicitada</td></tr><tr><td><code>results[].metadata.url</code></td><td>string</td><td>A URL buscada, após redirecionamentos</td></tr><tr><td><code>results[].metadata.statuses</code></td><td>objeto</td><td>status de processamento marcados de HTTP, análise e outros</td></tr><tr><td><code>params</code></td><td>objeto</td><td>Parâmetros usados na requisição, com os padrões preenchidos. Valores nulos são mantidos</td></tr><tr><td><code>metadata.timestamp</code></td><td>inteiro</td><td>timestamp Unix em segundos</td></tr><tr><td><code>metadata.request_id</code></td><td>string</td><td>Identificador da requisição</td></tr><tr><td><code>metadata.statuses</code></td><td>objeto</td><td>Status marcados no nível da requisição, como status de entrega de armazenamento</td></tr></tbody></table>


---

# 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/api-reference/pt-br/endpoints-principais.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.