> 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/documentation/es/empezar/inicio-rapido-web-api.md).

# Inicio rápido: Web API

Pasa de una clave de API a tu primera búsqueda y extracción con la Web API de Oxylabs en solo cinco minutos.

{% hint style="success" %}
¿Ya estás familiarizado con lo básico? Consulta [documentación de Web API](/products/es/api-web.md).
{% endhint %}

[**Oxylabs Web API**](https://oxylabs.io/products/web-api) le da a tu aplicación o a tu agente de IA dos cosas que la web abierta hace sorprendentemente difíciles: **encontrar las páginas correctas y recientes, y extraer sus datos de forma fiable**. Un endpoint busca en la web en tiempo real y el otro extrae cualquier página (renderiza JavaScript y gestiona los desafíos de acceso) y devuelve datos limpios listos para usar.

<table><thead><tr><th width="159">Endpoint</th><th>Te ofrece</th><th>Úsalo cuando</th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/web-api/search"><code>POST /v1/search</code></a></td><td>Resultados ordenados: título, descripción, URL</td><td>No sabes qué página contiene la respuesta</td></tr><tr><td><a href="https://developers.oxylabs.io/products/web-api/scrape"><code>POST /v1/scrape</code></a></td><td>Una página como Markdown, HTML, JSON o una captura de pantalla</td><td>Conoces la URL y necesitas su contenido</td></tr></tbody></table>

Están diseñados para usarse juntos: **busca para encontrar, extrae para obtener.** Esta guía de inicio rápido cubre:

* **Integración manual** – tu propio código llamando directamente a la API.
* **Integración sencilla de IA** – usando Web API a través de un agente de IA propietario o personalizado.

{% hint style="success" %}
¿Quieres probar Web API en un entorno sencillo basado en interfaz antes de la implementación completa? Consulta [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
{% endhint %}

## Configuración y clave API <a href="#docs-internal-guid-4566d081-7fff-6c77-5105-4c81aa345516" id="docs-internal-guid-4566d081-7fff-6c77-5105-4c81aa345516"></a>

1. **Crea una cuenta:** Regístrate en el [Oxylabs Dashboard](https://dashboard.oxylabs.io/).
2. **Añade una instancia de producto:** Haz clic en **+ Añadir instancia de producto** y selecciona Web API en la categoría de acceso web.
3. **Configura:** Elige el nombre de la instancia, los límites de uso del producto (opcional) y crea la instancia.
4. **Obtén las credenciales:** Haz clic en la instancia de Web API en la tabla de instancias de inicio del panel y obtén tu clave API.
5. **Exporta tu clave API** en el entorno de tu proyecto (p. ej., la terminal de tu sistema operativo o la terminal CLI en el espacio de trabajo del proyecto):

```bash
export OXYLABS_WEB_API_KEY=your_api_key_here
```

{% hint style="info" %}
**Nota:** Mantén siempre tu clave en el servidor. Nunca la subas al control de código fuente ni la expongas en el código del lado del cliente.
{% endhint %}

## Integración de Web API

#### ¿Lo integras en un agente de IA?

Salta a [Integraciones de agentes de IA](#ai-agent-integration) para empezar a usarlo con un solo comando.

#### ¿Estás creando tu propia integración personalizada?

Empieza con la integración manual a continuación.

### Integración manual

Según tus necesidades de datos, puedes usar los endpoints de Web API por separado para búsqueda web, scraping o como una canalización completa de recopilación y entrega de datos.

{% stepper %}
{% step %}

#### Busca páginas (`/search`)

Encuentra qué páginas contienen la respuesta a tu `consulta`:

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

<details>

<summary>Ejemplo de salida</summary>

```json
{
  "state": "done",
  "results": [
    {
      "title": "Implementation Timeline | EU Artificial Intelligence Act",
      "outline": [
        "Date 2 August 2025 Providers: need to be compliant with the AI Act by 2 August 2027..."
      ],
      "url": "https://artificialintelligenceact.eu/implementation-timeline/",
      "metadata": { "position": 1 }
    }
  ],
  "params": { "query": "eu ai act compliance deadlines", "location": null, "max_results": 3 },
  "metadata": { "timestamp": 1787431568, "request_id": "1788875675880097469" }
}
```

</details>
{% endstep %}

{% step %}

#### Extrae una página (`/scrape`)

Extrae el contenido completo de cualquier sitio web público pasando la página de destino `url` y el formato de salida deseado (`markdown`, `html`, `json`, `screenshot`). Aquí tienes una solicitud de contenido de página en Markdown:

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

{% endstep %}

{% step %}

#### Canalización completa (de búsqueda a extracción)

`outline` encontrado en `/search` es una lista de fragmentos truncados y a menudo no es útil para casos de uso avanzados o flujos de trabajo de IA.

Para obtener datos estructurados a partir de una sola consulta, busca en la web con `/search` datos relevantes según tu `consulta` y pasa la URL de resultado a `/scrape` para recuperar los datos. Aquí tienes un ejemplo completo de Python funcional:

{% code expandable="true" %}

```python
import os, requests

API = "https://webapi.oxylabs.io"
HEADERS = {"Authorization": f"Bearer {os.environ['OXYLABS_WEB_API_KEY']}"}

def research(question: str, read_top: int = 2) -> list[dict]:
    # 1. Descubre las URL de destino
    hits = requests.post(
        f"{API}/v1/search",
        headers=HEADERS,
        json={"query": question, "max_results": 10},
    )
    hits.raise_for_status()
    # 2. Extrae el contenido completo de la página como Markdown
    pages = []
    for hit in hits.json()["results"][:read_top]:
        page = requests.post(
            f"{API}/v1/scrape",
            headers=HEADERS,
            json={"url": hit["url"], "output": ["markdown"]},
            timeout=120,
        )
        if not page.ok:
            print(f"skipped {hit['url']}: {page.status_code}")
            continue
        pages.append(
            {
                "url": hit["url"],
                "title": hit["title"],
                "content": page.json()["results"][0]["markdown"],
            }
        )
    return pages

for page in research("eu ai act compliance deadlines"):
    print(f"--- {page['title']} ({page['url']})")
    print(page["content"][:500])
```

{% endcode %}
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Todo lo anterior es en tiempo real: el resultado vuelve en la respuesta.** Para recopilación de datos de gran volumen, recomendamos ejecutar los scrapers como trabajos bajo `/v1/async/scrape` y entregar mediante polling, callback o directamente a tu bucket. Consulta [Modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
{% endhint %}

### Integración de agente de IA

Oxylabs Web API está diseñada para flujos de trabajo sencillos de agentes de IA usando **Habilidades del agente**, **MCP** (Model Context Protocol) o simples **integraciones de un solo prompt**. Una vez que tengas tu clave API, elige el método de integración.

{% tabs %}
{% tab title="Integración de un solo prompt" icon="rectangle-terminal" %}
**Prompt de integración de una sola página: pega un prompt en un agente de programación y haz que cree una integración personalizada para ti.**

Si quieres que un asistente de programación de IA (como Claude Code, Cursor o Copilot) cree una integración para ti, pega el siguiente prompt:

{% code overflow="wrap" expandable="true" %}

```
Integra Oxylabs Web API en este proyecto para búsqueda web en vivo y lectura de páginas.

Lee https://developers.oxylabs.io/products/web-api/for-agents.md y sigue
sus instrucciones. Tiene la URL base, la autenticación, ambos esquemas de endpoint, el código de referencia, las reglas de error y reintento
y la lista de verificación que debes cumplir. Si la página no carga, detente y dímelo; no
reconstruyas la API de memoria.

Decide el camino y dime antes de escribir nada:
- ¿El propio código de este proyecto llamará a la API en tiempo de ejecución? -> escribe el cliente que la página
  especifica, siguiendo la forma en que esta base de código ya realiza llamadas HTTP salientes.
- ¿El acceso web es para ti durante esta sesión en lugar de para el código del proyecto?
  -> instala el servidor MCP y las skills, tal como describe la página.

La clave está en OXYLABS_WEB_API_KEY o en un .env aquí. Si no está en ninguno de los dos, pregúntame. Nunca
imprimas la clave: ni en el código, ni en los registros, ni en las pruebas, ni en tus respuestas.

Demuestra que funciona antes de escribir pruebas: haz una búsqueda real, extrae una URL de los
resultados y muéstrame ambos IDs de solicitud. Si una llamada devuelve 401, detente y dímelo.

Cuando una extracción vuelva vacía o escasa, inténtalo una vez más con run_js: true. Si sigue
vacía y el sitio está en un TLD de país (.lt, .es, .co.uk), inténtalo una vez más con run_js y
location configurada para ese país, y luego informa que la página no se puede leer.

Luego añade una prueba para el reintento y el mapeo de errores contra un transporte simulado y ejecútala.
Si no puedes ejecutar comandos en este entorno, dilo una vez y dame los
comandos exactos para ejecutar en su lugar.

Reporta: el camino que tomaste, cada elemento de la lista de verificación de la página marcado como hecho o no,
lo que aún debo hacer yo mismo y cualquier cosa que no pudiste terminar. No me preguntes
si debo continuar; haz el trabajo.
```

{% endcode %}

Consulta un ejemplo completo y aprende más sobre la integración de Web API en la [documentación](https://developers.oxylabs.io/products/web-api).
{% endtab %}

{% tab title="Habilidades del agente" icon="head-side-gear" %}
**Habilidades del agente – instala el conocimiento sobre cómo usar la API; no requiere ejecutar un servidor.**

Añade habilidades oficiales para agentes que enseñan a tu agente de IA cómo buscar, extraer, citar fuentes y gestionar la investigación web a través de Oxylabs Web API usando el siguiente comando de terminal:

```bash
npx skills add oxylabs/web-api-skills
```

Ahora tu agente sabe todo lo que hay que saber sobre Oxylabs Web API y cómo usarla. Para saber más sobre las habilidades de agente de Web API, consulta nuestro [documentación](https://developers.oxylabs.io/ai-workflows/agent-skills).
{% endtab %}

{% tab title="Servidor MCP" icon="server" %}
**Servidor MCP – herramientas tipadas para búsqueda, extracción y scrapers dedicados para cualquier cliente MCP.**

Aloja tú mismo nuestro servidor MCP oficial para exponer directamente a Claude Code, Cursor o tu agente de IA personalizado las herramientas de búsqueda, extracción y extracción de Web API:

```bash
uv tool install git+https://github.com/oxylabs/web-api-mcp
```

Para obtener más información sobre la integración MCP de Web API, consulta [Servidor MCP](https://developers.oxylabs.io/ai-workflows/mcp).
{% endtab %}
{% endtabs %}

### Parámetros esenciales

#### /search <a href="#docs-internal-guid-5786cd1b-7fff-0a37-d2dd-abcf76c7e3ef" id="docs-internal-guid-5786cd1b-7fff-0a37-d2dd-abcf76c7e3ef"></a>

<table><thead><tr><th width="121">Parámetro</th><th width="86">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>consulta</code></td><td>cadena</td><td>Palabra clave o frase de búsqueda</td></tr><tr><td><code>max_results</code></td><td>entero</td><td>Número de resultados orgánicos de búsqueda a devolver (<code>1-20</code>)</td></tr><tr><td><code>location</code></td><td>cadena</td><td>código de país de 2 letras (p. ej., <code>"DE"</code>, <code>"US"</code>) para búsqueda localizada</td></tr></tbody></table>

#### /scrape

<table><thead><tr><th width="111">Parámetro</th><th width="99">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>url</code></td><td>cadena</td><td>URL a extraer</td></tr><tr><td><code>output</code></td><td>arreglo</td><td>Formatos a devolver: <code>"html"</code> (predeterminado), <code>"markdown"</code>, <code>"json"</code>, <code>"screenshot"</code></td></tr><tr><td><code>json</code></td><td>objeto</td><td>Usado para análisis personalizado de IA mediante prompt o esquema</td></tr><tr><td><code>location</code></td><td>cadena</td><td>código de país de 2 letras (p. ej., <code>"DE"</code>, <code>"US"</code>). Algunos scrapers dedicados usan un formato diferente. Consulta <a href="/products/es/api-web/scrape/scrapers-dedicados.md">Scrapers dedicados</a>.</td></tr><tr><td><code>run_js</code></td><td>booleano</td><td>Renderiza la página en un navegador real antes de capturar el contenido. Es más lento; usa un timeout del cliente de <code>150</code>s o más.</td></tr><tr><td><code>device</code></td><td>cadena</td><td>Emulación de dispositivo: <code>"desktop"</code> (predeterminado) o <code>"mobile"</code>.</td></tr></tbody></table>

### Códigos de respuesta comunes

<table><thead><tr><th width="112">Estado</th><th width="322">Significado</th><th>¿Reintentar?</th></tr></thead><tbody><tr><td><code>200</code> / <code>202</code></td><td>Éxito. Realtime / trabajo asíncrono aceptado</td><td>–</td></tr><tr><td><code>400</code></td><td>Solicitud malformada</td><td>No, corrige el campo indicado en <code>errors[].pointer</code>.</td></tr><tr><td><code>401</code></td><td>Error de autenticación (clave API incorrecta o faltante).</td><td>No, comprueba la clave en tu instancia de Web API</td></tr><tr><td><code>429</code></td><td>Límite de velocidad o cuota agotada</td><td>Límite de velocidad: sí, con backoff. Cuota: no.</td></tr><tr><td><code>5xx</code></td><td>Fallo del sistema upstream o error al extraer</td><td>Sí, hasta ~3 intentos con backoff.</td></tr></tbody></table>

Ver todos [códigos de respuesta](https://developers.oxylabs.io/products/web-api/troubleshooting) para conocer todos los códigos de estado y encontrar consejos de solución de problemas.

## Siguientes pasos

* **¿Quieres la visión completa del producto?** Consulta el [documentación de Web API](https://developers.oxylabs.io/products/web-api).
* **¿Estás creando tus primeras solicitudes personalizadas?** Prototipa más rápido con [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
* **¿Necesitas datos de un sitio específico?** Consulta todo sobre Web API [Scrapers dedicados](https://developers.oxylabs.io/products/web-api/scrape/dedicated-scrapers).
* **¿Quieres JSON estructurado de cualquier página?** Prueba la función integrada de Web API [Análisis de IA](https://developers.oxylabs.io/products/web-api/scrape/ai-parsing).
* **¿Extracción a gran escala o entrega a almacenamiento en la nube?** Obtén más información sobre los [Modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
* **¿Quieres que un agente de IA use Web API sin que escribas código?** Prueba las soluciones oficiales de Oxylabs [Servidor MCP](https://developers.oxylabs.io/ai-workflows/mcp) o [Habilidades del agente](https://developers.oxylabs.io/ai-workflows/agent-skills).


---

# 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/documentation/es/empezar/inicio-rapido-web-api.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.