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

# Modos de entrega

Descubre cómo la Web API entrega resultados: respuestas en tiempo real, trabajos asíncronos con sondeo o callbacks, entrega en almacenamiento en la nube y solicitudes por lotes.

La Web API ofrece tres modos de entrega para distintos requisitos de carga de trabajo y volúmenes de ejecución. 

<table><thead><tr><th width="315">Entrega</th><th width="92">Máximo de elementos</th><th width="143">Destinos</th><th width="215">Se usa para...</th></tr></thead><tbody><tr><td><a href="#realtime"><strong>Realtime</strong></a> (Sincrónico)<br><code>POST /v1/scrape/{source}</code></td><td>1</td><td>Todos los endpoints</td><td>Solicitudes de baja latencia, pruebas</td></tr><tr><td><a href="#single-job-delivery-async"><strong>Asíncrono individual</strong></a> (sondeo)<br><code>POST /v1/async/scrape/{source}</code></td><td>1</td><td>Todos los endpoints</td><td>Alta concurrencia y volumen</td></tr><tr><td><a href="#batch-delivery-async"><strong>Lote asíncrono</strong></a> (cola masiva)<br><code>POST /v1/async/scrape/batch/{source}</code></td><td>5,000</td><td>Selecciona endpoints</td><td>Ingesta masiva</td></tr></tbody></table>

La mayoría `/scrape` endpoints se ofrecen como opciones para **Realtime** y **Asíncrono** entrega de resultados, y la ruta decide cuándo y cómo obtienes el resultado.

```http
POST /v1/scrape/...          # realtime: el resultado es la respuesta
POST /v1/async/scrape/...    # async: crea un trabajo y recupera el resultado por separado
```

## Realtime

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

La entrega Realtime procesa el scrape en la conexión HTTP inicial. La solicitud se bloquea hasta que el renderizado, la resolución de acceso y el análisis se completan, devolviendo la carga útil de contenido en el cuerpo de la respuesta. Configura un tiempo de espera del cliente de al 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" %}
Algunos endpoints no admiten entrega Realtime (p. ej., descargas de YouTube, ChatGPT, Gemini, Perplexity). Confirma la elegibilidad de tu destino con [Descubrimiento de endpoints](/products/es/api-web/scrape/descubrimiento-de-endpoints.md) o consulta la [Referencia de la API](https://developers.oxylabs.io/api-reference).
{% endhint %}

## Entrega de un solo trabajo (Asíncrona)

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

La entrega asíncrona de un solo trabajo encola una solicitud de scrape y devuelve inmediatamente un HTTP `202 Accepted` de estado que contiene el identificador del trabajo.

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

Cuando un trabajo es aceptado, el ID del trabajo se devuelve dentro de `metadata.request_id`.

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

El estado del trabajo enviado puede consultarse a través del `estado` resultados:

<table data-header-hidden><thead><tr><th width="172"></th><th></th></tr></thead><tbody><tr><td><code>status: "pending"</code></td><td>El trabajo está en cola o en ejecución. El <code>resultados</code> array permanece vacío (<code>[]</code>).</td></tr><tr><td><code>status: "done"</code></td><td>Trabajo completado. El <code>resultados</code> array contiene la salida analizada.</td></tr><tr><td><code>status: "faulted"</code></td><td>La extracción falló. Revisa <code>results[].metadata.status_code</code> para más detalles.</td></tr></tbody></table>

### Recuperación de resultados

Los resultados se recuperan mediante [sondeo](#option-a-polling-endpoint-get-v1-async-scrape-jobid), [webhooks](#option-b-webhooks-callback_url) (URL de callback), o mediante [cargas a almacenamiento en la nube](#option-c-cloud-bucket-upload-storage).

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

Pasa el identificador numérico `metadata.request_id` al endpoint de sondeo.

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

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

Incluye `callback_url` en el cuerpo inicial de la solicitud. Una vez que la ejecución cambia a `done` o `faulted`, la API envía un HTTP `POST` con la carga útil que contiene los resultados del trabajo a tu endpoint especificado.

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

La URL se valida al enviarla y las mal formadas se rechazan con error `400`.

#### **Carga a almacenamiento en la nube (`almacenamiento`)**

`almacenamiento` escribe el resultado en un bucket en lugar del cuerpo de la respuesta. Solo rutas asíncronas.

```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 del resultado                          |

{% hint style="danger" %}
**`storage.url` no se valida.** Se acepta un destino mal formado o mal escrito, el trabajo se ejecuta y se factura con entrega fallida.

**`storage.type` se comprueba con la lista anterior.** Un tipo incorrecto te devuelve `400`. Prueba el destino una vez con una solicitud individual antes de usar un lote.
{% endhint %}

## Entrega por lotes (Asíncrona)

{% hint style="warning" %}
El enrutamiento por lotes solo está disponible para determinados `/scrape` orígenes. Confirma la elegibilidad de tu destino con [Descubrimiento de endpoints](/products/es/api-web/scrape/descubrimiento-de-endpoints.md) o consulta la [Referencia de la API](https://developers.oxylabs.io/api-reference).
{% endhint %}

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

La entrega por lotes envía hasta 5.000 trabajos de scraping en una sola solicitud HTTP. En lugar de tomar una sola `url` o `query` cadena, el campo de entrada acepta un array de cadenas. Todos los demás campos de la carga útil se aplican a cada trabajo del 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"]
  }'
```

Los endpoints por lotes devuelven un HTTP `202 Accepted` con un array de estados individuales de trabajos en `data[]` junto con un `errors[]` array que enumera los elementos rechazados (p. ej., formato de ASIN no válido o sintaxis de URL no válida). Consulta el ejemplo abajo:

<details>

<summary>Ejemplo de salida</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 should only contain alphanumeric values.",
      "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/es/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.