> 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/pt-br/api-web/scrape/modos-de-entrega.md).

# Modos de entrega

Descubra como a API Web entrega os resultados: respostas em Realtime, jobs assíncronos com polling ou callbacks, entrega em armazenamento em nuvem e solicitações em lote.

A Web API oferece três modos de entrega para diferentes requisitos de carga de trabalho e volumes de execução. 

<table><thead><tr><th width="315">Entrega</th><th width="92">Máx. de itens</th><th width="143">Destinos</th><th width="215">Usado para...</th></tr></thead><tbody><tr><td><a href="#realtime"><strong>Realtime</strong></a> (Síncrono)<br><code>POST /v1/scrape/{source}</code></td><td>1</td><td>Todos os endpoints</td><td>Solicitações de baixa latência, testes</td></tr><tr><td><a href="#single-job-delivery-async"><strong>Assíncrono único</strong></a> (consulta periódica)<br><code>POST /v1/async/scrape/{source}</code></td><td>1</td><td>Todos os endpoints</td><td>Alta concorrência e volume</td></tr><tr><td><a href="#batch-delivery-async"><strong>Lote assíncrono</strong></a> (fila em lote)<br><code>POST /v1/async/scrape/batch/{source}</code></td><td>5,000</td><td>Selecionar endpoints</td><td>Ingestão em massa</td></tr></tbody></table>

A maioria `/scrape` endpoints são oferecidos como opções para **Realtime** e **Assíncrono** a entrega do resultado, com o caminho decidindo quando e como você recebe o resultado.

```http
POST /v1/scrape/...          # realtime: the result is the response
POST /v1/async/scrape/...    # async: create a job and retrieve the result separately
```

## Realtime

```http
POST /v1/scrape/{source}
```

A entrega Realtime processa a raspagem na conexão HTTP inicial. A solicitação fica bloqueada até que a renderização, a resolução de acesso e a análise sejam concluídas, retornando a carga útil do conteúdo no corpo da resposta. Defina um timeout do cliente de pelo menos 150 segundos.

```bash
curl -X POST https://webapi.oxylabs.io/v1/scrape/amazon/product \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "B0CX23V2ZK",
    "domain": "com",
    "output": ["json"]
  }'
```

{% hint style="info" %}
Alguns endpoints não suportam entrega Realtime (por exemplo, downloads do YouTube, ChatGPT, Gemini, Perplexity). Confirme a elegibilidade do seu alvo com [Descoberta de endpoints](/products/pt-br/api-web/scrape/descoberta-de-endpoints.md) ou verifique a [Referência da API](https://developers.oxylabs.io/api-reference).
{% endhint %}

## Entrega de tarefa única (Assíncrono)

```http
POST /v1/async/scrape/{source}
```

A entrega assíncrona de tarefa única enfileira uma solicitação de raspagem e retorna imediatamente um HTTP `202 Accepted` status contendo o identificador da tarefa.

```bash
curl https://webapi.oxylabs.io/v1/async/scrape/media/youtube/metadata \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query": "a1cWkClBXLI", "output": ["json"]}'
```

Quando uma tarefa é aceita, o ID da tarefa é retornado dentro de `metadata.request_id`.

```json
{
  "status": "pending",
  "params": { "query": "a1cWkClBXLI", "output": ["json"] },
  "metadata": { "timestamp": 1787599164, "request_id": "7497734325668954113" }
}
```

O status da tarefa enviada pode ser consultado por meio do `status` resultados:

<table data-header-hidden><thead><tr><th width="172"></th><th></th></tr></thead><tbody><tr><td><code>status: "pending"</code></td><td>A tarefa está em fila ou em execução. O <code>results</code> array permanece vazio (<code>[]</code>).</td></tr><tr><td><code>status: "done"</code></td><td>Tarefa concluída. O <code>results</code> array contém a saída analisada.</td></tr><tr><td><code>status: "faulted"</code></td><td>A extração falhou. Inspecione <code>results[].metadata.status_code</code> para detalhes.</td></tr></tbody></table>

### Recuperação da saída

Os resultados são recuperados via [consulta periódica](#option-a-polling-endpoint-get-v1-async-scrape-jobid), [webhooks](#option-b-webhooks-callback_url) (URL de callback), ou envio direto [uploads para armazenamento em nuvem](#option-c-cloud-bucket-upload-storage).

#### **Endpoint de polling (`GET /v1/async/scrape/{jobId}`)**

Passe o número `metadata.request_id` para o endpoint de polling.

```bash
curl -X GET https://webapi.oxylabs.io/v1/async/scrape/7497971512142465025 \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY"
```

#### **Webhooks (`callback_url`)**

Inclua `callback_url` no corpo inicial da solicitação. Quando a execução transitar para `done` ou `faulted`, a API emite um HTTP `POST` payload contendo os resultados da tarefa para o endpoint especificado.

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "callback_url": "https://your-api.example.com/webhooks-oxylabs"
}
```

A URL é validada no momento do envio e as malformadas são rejeitadas com o erro `400`.

#### **Envio para armazenamento em nuvem (`storage`)**

`storage` grava o resultado em um bucket em vez do corpo da resposta. Apenas caminhos assíncronos.

```json
{
  "query": "B0CX23V2ZK",
  "output": ["json"],
  "storage": {
    "type": "s3",
    "url": "s3://your-bucket-name/scraped-data/B0CX23V2ZK.json"
  }
}
```

| Campo          | Valores                                        |
| -------------- | ---------------------------------------------- |
| `storage.type` | `s3`, `s3_gzip`, `s3_compatible`, `gcs`, `tos` |
| `storage.url`  | Destino do resultado                           |

{% hint style="danger" %}
**`storage.url` não é validado.** Um destino malformado ou escrito incorretamente é aceito, a tarefa é executada e cobrada com entrega falha.

**`storage.type` é verificado em relação à lista acima.** Um tipo inválido gera `400`. Teste o destino uma vez com uma solicitação única antes de usar um lote.
{% endhint %}

## Entrega em lote (Assíncrono)

{% hint style="warning" %}
O roteamento em lote está disponível apenas para alguns `/scrape` sources. Confirme a elegibilidade do seu alvo com [Descoberta de endpoints](/products/pt-br/api-web/scrape/descoberta-de-endpoints.md) ou verifique a [Referência da API](https://developers.oxylabs.io/api-reference).
{% endhint %}

```http
POST /v1/async/scrape/batch/{source}
```

A entrega em lote envia até 5.000 tarefas de raspagem em uma única solicitação HTTP. Em vez de aceitar uma única `URL` ou `consulta` string, o campo de entrada aceita um vetor de strings. Todos os outros campos no payload são aplicados a cada tarefa do lote.

```bash
curl -X POST https://webapi.oxylabs.io/v1/async/scrape/batch/amazon/product \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["B0CX23V2ZK", "B09B33PQS9", "INVALID_ASIN_XYZ"],
    "domain": "com",
    "output": ["json"]
  }'
```

Os endpoints em lote retornam um HTTP `202 Accepted` status com um array de status individuais de tarefas em `data[]` junto com um `errors[]` vetor listando itens rejeitados (por exemplo, formatação inválida de ASIN ou sintaxe de URL inválida). Veja o exemplo abaixo:

<details>

<summary>Exemplo de saída</summary>

```json
{
  "data": [
    {
      "state": "pending",
      "params": {
        "query": "B0CX23V2ZK",
        "output": [
          "json"
        ],
        "json": {
          "schema": null,
          "prompt": null
        },
        "location": null,
        "device": "desktop",
        "run_js": null,
        "storage": {
          "type": null,
          "url": null
        },
        "callback_url": null,
        "client_notes": null,
        "domain": "com",
        "locale": null,
        "autoselect_variant": false,
        "check_empty_geo": null,
        "safe_search": true,
        "currency": null
      },
      "metadata": {
        "timestamp": 1790852882,
        "request_id": "7511381408825235457"
      }
    },
    {
      "state": "pending",
      "params": {
        "query": "B09B33PQS9",
        "output": [
          "json"
        ],
        "json": {
          "schema": null,
          "prompt": null
        },
        "location": null,
        "device": "desktop",
        "run_js": null,
        "storage": {
          "type": null,
          "url": null
        },
        "callback_url": null,
        "client_notes": null,
        "domain": "com",
        "locale": null,
        "autoselect_variant": false,
        "check_empty_geo": null,
        "safe_search": true,
        "currency": null
      },
      "metadata": {
        "timestamp": 1790852882,
        "request_id": "7511381408825229313"
      }
    }
  ],
  "errors": [
    {
      "detail": "ASIN deve conter apenas valores alfanuméricos.",
      "pointer": "/query/2"
    }
  ]
}
```

</details>


---

# 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/pt-br/api-web/scrape/modos-de-entrega.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.