> 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/jobs-e-descoberta.md).

# Jobs e descoberta

Referência para enviar, agrupar e coletar jobs de scraping assíncronos, e para listar endpoints e parâmetros em tempo de execução.

<table><thead><tr><th width="112.5">Seção</th><th>Endpoints</th></tr></thead><tbody><tr><td>Requisições</td><td><code>POST /v1/async/scrape/{path}</code>, <code>POST /v1/async/scrape/batch/{path}</code>, <code>GET /v1/async/scrape/{request_id}</code></td></tr><tr><td>Descoberta</td><td><code>GET /v1/scrapers</code>, <code>OPTIONS /v1/{endpoint}</code></td></tr></tbody></table>

## Requisições assíncronas

### `POST /v1/async/scrape/{path}`

Envia uma requisição assíncrona de raspagem. `{path}` é qualquer caminho de raspagem com `/v1/async/scrape/` no lugar de `/v1/scrape/`.

**Modos:** `assíncrono`

<table><thead><tr><th width="151">Nome</th><th width="98">Tipo</th><th width="106.5">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>URL de webhook para a requisição concluída. URLs malformadas são rejeitadas com <code>400</code></td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega o resultado para um bucket em vez da resposta</td></tr><tr><td><code>storage.type</code></td><td>string</td><td>sim, com <code>storage</code></td><td><code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>, ou <code>tos</code>. Validado</td></tr><tr><td><code>storage.url</code></td><td>string</td><td>sim, com <code>storage</code></td><td>Destino do resultado. Validado para <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, e <code>tos</code>. Valores inválidos retornam <code>400</code> antes que a requisição seja criada</td></tr></tbody></table>

Todos os outros parâmetros são os do endpoint enviado.

#### **Resposta** – `202 Aceito`

<table><thead><tr><th width="207">Campo</th><th width="95">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>state</code></td><td>string</td><td><code>pendente</code></td></tr><tr><td><code>params</code></td><td>object</td><td>A requisição como executada, 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>O ID da requisição. Use-o para coletar o resultado</td></tr></tbody></table>

### `POST /v1/async/scrape/batch/{path}`

Envia uma requisição por valor em uma lista. `{path}` é qualquer caminho de raspagem que tenha modo em lote.

**Modos:** `lote`

<table><thead><tr><th width="131.5">Nome</th><th width="93">Tipo</th><th width="158.5">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>query</code></td><td>array de strings</td><td>sim, se o endpoint aceitar <code>query</code></td><td>Valores, uma requisição por valor</td></tr><tr><td><code>url</code></td><td>array de strings</td><td>sim, se o endpoint aceitar <code>url</code></td><td>URLs, uma requisição por valor</td></tr><tr><td><code>callback_url</code></td><td>string</td><td>não</td><td>URL de webhook para cada requisição concluída</td></tr><tr><td><code>storage</code></td><td>object</td><td>não</td><td>Entrega para bucket para cada requisição. Mesmos campos acima</td></tr></tbody></table>

Todos os outros parâmetros são os do endpoint enviado e se aplicam a cada requisição. Use o campo singular `query` ou `url` com um valor de array. `queries` e `urls` não são aceitos.

#### **Resposta** – `202 Aceito`

<table><thead><tr><th width="261">Campo</th><th width="141.5">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>data[]</code></td><td>array</td><td>Um objeto por requisição aceita. Omitido quando nenhuma requisição é aceita</td></tr><tr><td><code>errors[]</code></td><td>array</td><td>Um objeto de erro por item rejeitado. Omitido quando nenhum item é rejeitado</td></tr><tr><td><code>data[].state</code></td><td>string</td><td><code>pendente</code></td></tr><tr><td><code>data[].params</code></td><td>object</td><td>A requisição como executada</td></tr><tr><td><code>data[].metadata.request_id</code></td><td>string</td><td>O ID da requisição</td></tr></tbody></table>

Não há rota de coleta em lote: colete cada requisição pelo seu `request_id`. `/v1/scrape/batch` retorna `404`.

### `GET /v1/async/scrape/{request_id}`

Retorna o estado e o resultado de uma requisição enviada. Envie `metadata.request_id` da resposta de envio como o `request_id` parâmetro de caminho.

#### **Resposta** – `200 OK`

<table><thead><tr><th width="118">Campo</th><th width="76">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>state</code></td><td>string</td><td><code>pendente</code> enquanto a requisição estiver em fila ou em execução, <code>concluído</code> quando concluída</td></tr><tr><td><code>results[]</code></td><td>array</td><td>Mesma estrutura da resposta Realtime. Preenchido quando <code>state</code> é <code>concluído</code></td></tr></tbody></table>

Um request\_id desconhecido ou expirado `request_id` retorna `404`.

## Descoberta

### `GET /v1/scrapers`

Lista os caminhos de raspagem Realtime implementados para o cliente.

#### **Resposta** – `200 OK`

```json
{
  "scrapers": [
    "/v1/scrape",
    "/v1/scrape/amazon",
    "/v1/scrape/amazon/product",
    "/v1/scrape/google/search"
    ...
  ]
}
```

<table><thead><tr><th width="113">Campo</th><th width="86.5">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>scrapers</code></td><td>array de strings</td><td>Caminhos de raspagem Realtime implementados disponíveis para o cliente</td></tr></tbody></table>

### `OPTIONS /v1/{endpoint}`

Retorna uma especificação de parâmetros para um endpoint. A resposta não é um corpo de requisição executável. Ela lista os parâmetros aceitos, anotados com seu tipo, obrigatoriedade, valores permitidos, padrão, limites de tamanho e descrição.

`OPTIONS /v1/search` não está disponível.

#### **Resposta** (`OPTIONS /v1/scrape`)

```json
{
  "url": "[string] [required] [max_len: 8192]. A URL da página a ser raspada.",
  "output": [
    "[string] [optional] [enum: html, screenshot, Markdown, json] [default: html]. `html` é o código-fonte da página, `Markdown` a versão convertida, `screenshot` um png e `json` os dados analisados."
  ],
  "json": {
    "schema": "[json] [min_len: 10] [max_len: 65535]. O esquema JSON no qual a página raspada é convertida para saída `json`. Não pode ser usado junto com `json.prompt`.",
    "prompt": "[string] [max_len: 8192]. O prompt que nomeia os dados nos quais a página raspada é convertida para saída `json`. Não pode ser usado junto com `json.schema`."
  },
  "location": "[string] [optional]. País de onde o scrape é feito, como um código ISO 3166-1 alpha-2, por exemplo `US`."
  "device": "[string] [optional] [enum: desktop, mobile] [default: desktop]. Dispositivo para o qual a página raspada é renderizada."
  "run_js": "[bool] [optional]. Renderiza a página usando JavaScript antes de raspá-la, necessário para a saída `screenshot`."
}
```

#### **Formato de saída**

Valor de cada parâmetro: `[tipo] [obrigatório ou opcional] [restrições]. Descrição.`

<table><thead><tr><th width="297">Token</th><th>Significado</th></tr></thead><tbody><tr><td><code>[cadeia de caracteres], [booleano], [inteiro], [json]</code></td><td>Tipo do parâmetro</td></tr><tr><td><code>[obrigatório], [opcional]</code></td><td>Se o parâmetro deve ser enviado. Não mostrado em todos os parâmetros</td></tr><tr><td><code>[enum: a, b]</code></td><td>Valores permitidos</td></tr><tr><td><code>[padrão: x]</code></td><td>Valor usado quando o parâmetro é omitido</td></tr><tr><td><code>[min_len: n], [max_len: n]</code></td><td>Comprimento mínimo e máximo</td></tr></tbody></table>

Arrays mostrados como um array de um único elemento contendo a anotação do elemento. Objetos aninhados são mostrados como objetos. Caminhos assíncronos também listam `storage` e `callback_url`.


---

# 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/jobs-e-descoberta.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.