> 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 Oxylabs Web API en solo cinco minutos.

{% hint style="success" %}
¿Ya conoces los conceptos básicos? Consulta la [documentación de Web API](https://developers.oxylabs.io/products/es/api-web.md).
{% endhint %}

[**Oxylabs Web API**](https://oxylabs.io/products/web-api) ofrece a tu aplicación o agente de IA dos cosas que la web abierta hace sorprendentemente difíciles: **encontrar las páginas adecuadas y actualizadas, y extraer sus datos de forma fiable**. Un endpoint busca en la web en tiempo real y el otro extrae datos de 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>Qué ofrece</th><th>Cuándo usarlo</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 por relevancia: título, descripción y URL</td><td>No sabes en qué página está 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 en formato Markdown, HTML, JSON o captura de pantalla</td><td>Conoces la URL y necesitas obtener su contenido</td></tr></tbody></table>

Están diseñados para usarse juntos: **buscar para encontrar y extraer para obtener los datos.** Esta guía de inicio rápido abarca:

* **Integración manual** – tu propio código que llama directamente a la API.
* **Integración sencilla con IA** – usar Web API mediante un agente de IA propio o personalizado.

{% hint style="success" %}
¿Quieres probar Web API en un entorno sencillo con interfaz gráfica antes de implementarla por completo? Consulta [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
{% endhint %}

## Configuración y clave de 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 [panel de control de Oxylabs](https://dashboard.oxylabs.io/).
2. **Añade una instancia de producto:** Haz clic en **+ Add product instance** y selecciona Web API en la categoría Web access.
3. **Configura:** Elige el nombre de la instancia y 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 la página de inicio del panel de control y obtén tu clave de API.
5. **Exporta tu clave de API** al entorno de tu proyecto (por ejemplo, la terminal de tu sistema operativo o la terminal de CLI del 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 incluyas en el control de versiones ni la expongas en código del lado del cliente.
{% endhint %}

## Integración de Web API

#### ¿Vas a integrarla en un agente de IA?

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

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

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

### Integración manual

Según tus necesidades de datos, puedes usar los endpoints de Web API por separado para buscar en la web o extraer datos, o bien como una canalización completa de recopilación y entrega de datos.

{% stepper %}
{% step %}

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

Encuentra las páginas que contienen la respuesta a tu `query`:

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

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

Extrae el contenido completo de cualquier página web pública pasando la `url` de destino y el formato de salida deseado (`markdown`, `html`, `json`, `screenshot`). Esta es una solicitud del contenido de una 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 %}

#### Flujo completo (de búsqueda a extracción)

`outline` que se encuentra en `/search` es una lista de fragmentos truncados que a menudo no resulta útil para casos de uso avanzados o flujos de trabajo con IA.

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

{% 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. Discover target URLs
    hits = requests.post(
        f"{API}/v1/search",
        headers=HEADERS,
        json={"query": question, "max_results": 10},
    )
    hits.raise_for_status()
    # 2. Extraer 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 Realtime: el resultado se devuelve en la respuesta.** Para recopilar grandes volúmenes de datos, recomendamos ejecutar los scrapers como trabajos en `/v1/async/scrape` y entregar los datos mediante sondeo, callback o directamente en tu bucket. Consulta [Modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
{% endhint %}

### Integración con agentes de IA

Oxylabs Web API está diseñada para facilitar los flujos de trabajo de agentes de IA mediante **Agent Skills**, **MCP** (Model Context Protocol) o **integraciones con una sola instrucción**. Una vez que tengas tu clave de API, elige el método de integración.

{% tabs %}
{% tab title="Integración con una sola instrucción" icon="rectangle-terminal" %}
**Instrucción de integración de una página: pega una instrucción en un agente de programación para que cree una integración personalizada.**

Si quieres que un asistente de programación con IA (como Claude Code, Cursor o Copilot) cree una integración, pega la siguiente instrucción:

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

```
Integra Oxylabs Web API en este proyecto para realizar búsquedas web en directo y leer páginas.

Lee https://developers.oxylabs.io/products/web-api/for-agents.md y sigue
sus instrucciones. Incluye la URL base, la autenticación, los esquemas de ambos endpoints, el código de referencia, las reglas de errores y reintentos
y la lista de comprobación que debes cumplir. Si la página no se carga, detente y avísame; no
reconstruyas la API de memoria.

Decide cómo proceder y dímelo antes de escribir nada:
- ¿El código de este proyecto llamará a la API en tiempo de ejecución? -> escribe el cliente que especifica la página,
  siguiendo la forma en que este código base ya realiza llamadas HTTP salientes.
- ¿Necesitas acceso web durante esta sesión, en lugar de que lo use el código del proyecto?
  -> instala el servidor MCP y las skills tal como se describe en la página.

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

Comprueba que funciona antes de escribir las pruebas: realiza una búsqueda real, extrae una URL de los
resultados y muéstrame los dos ID de solicitud. Si una llamada devuelve 401, detente y avísame.

Cuando una extracción devuelve un resultado vacío o escaso, vuelve a intentarlo una vez con run_js: true. Si sigue
vacío y el sitio usa un dominio de nivel superior de país (.lt, .es, .co.uk), vuelve a intentarlo una vez más con run_js y
configura location en ese país; después, indica que la página no se puede leer.

Luego, añade una prueba del reintento y de la asignación de errores con un transporte simulado y ejecútala.
Si no puedes ejecutar comandos en este entorno, dilo una sola vez e indica los comandos exactos
que debo ejecutar en su lugar.

Informa de la ruta que seguiste, de si marcaste cada elemento de la lista de verificación de la página como completado o no,
de lo que todavía tengo que hacer por mi cuenta y de cualquier cosa que no hayas podido terminar. No me preguntes
si debes continuar; haz el trabajo.
```

{% endcode %}

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

{% tab title="Habilidades de agente" icon="head-side-gear" %}
**Las habilidades de agente instalan los conocimientos necesarios para usar la API; no se requiere ejecutar un servidor.**

Añade las habilidades oficiales de agente que enseñan a tu agente de IA a buscar, extraer datos, citar fuentes y realizar investigaciones web con Oxylabs Web API mediante el siguiente comando de terminal:

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

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

{% tab title="Servidor MCP" icon="server" %}
**El servidor MCP ofrece herramientas tipadas para buscar y extraer datos, además de extractores especializados para cualquier cliente MCP.**

Conéctate a nuestro servidor MCP oficial o alójalo por tu cuenta para ofrecer las herramientas de búsqueda, extracción de datos y extracción de Web API directamente a Claude Code, Cursor o a tu agente de IA personalizado.

Para implementarlo fácilmente, añade el servidor a tu cliente indicando a tu agente el servidor alojado por Oxylabs: `https://mcp.oxylabs.io/web-api-mcp`:

<details>

<summary><i class="fa-claude">:claude:</i>  <strong>Claude Code</strong></summary>

```bash
claude mcp add --transport http --scope user oxylabs-web-api \
  https://mcp.oxylabs.io/web-api-mcp \
  --header "Authorization: Bearer ${OXYLABS_WEB_API_KEY}"
```

</details>

<details>

<summary><i class="fa-openai">:openai:</i>  <strong>ChatGPT/Codex</strong></summary>

```bash
codex mcp add oxylabs-web-api \
  --url https://mcp.oxylabs.io/web-api-mcp \
  --bearer-token-env-var OXYLABS_WEB_API_KEY
```

</details>

<details>

<summary><i class="fa-cursor">:cursor:</i>  <strong>Cursor</strong> (u otros clientes que admitan encabezados personalizados)</summary>

Para cualquier cliente compatible con servidores MCP remotos y encabezados personalizados, añade la URL del servidor y un encabezado `Authorization` a la configuración MCP del cliente. Por ejemplo, en el archivo `mcp.json`:

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "url": "https://mcp.oxylabs.io/web-api-mcp",
      "headers": {
        "Authorization": "Bearer ${env:OXYLABS_WEB_API_KEY}"
      }
    }
  }
}
```

Los nombres de los campos pueden variar según el cliente. Consulta su documentación para saber cómo añadir un servidor MCP remoto con encabezados.

</details>

Para obtener más información sobre la integración de Web API MCP o sobre cómo alojar por tu cuenta el servidor oficial de Oxylabs, consulta [Servidores 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>query</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 de búsqueda orgánicos que se devolverán (<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úsquedas localizadas</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 que se va a extraer</td></tr><tr><td><code>output</code></td><td>matriz</td><td>Formatos que se devolverán: <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>Se usa para el análisis personalizado con IA mediante una instrucción o un 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="https://developers.oxylabs.io/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 tiempo de espera 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>Correcto. Se aceptó el trabajo Realtime/asíncrono</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 de API incorrecta o ausente).</td><td>No, comprueba la clave en tu instancia de Web API</td></tr><tr><td><code>429</code></td><td>Límite de solicitudes alcanzado o cuota agotada</td><td>Límite de solicitudes: sí, con espera progresiva. Cuota: no.</td></tr><tr><td><code>5xx</code></td><td>Fallo del servidor de origen o error al extraer datos</td><td>Sí, hasta ~3 intentos con espera progresiva.</td></tr></tbody></table>

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

## Próximos pasos

* **¿Estás creando tus primeras solicitudes personalizadas?** Crea prototipos más rápido con [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
* **¿Necesitas datos de un sitio específico?** Descubre todos los [scrapers especializados de Web API](https://developers.oxylabs.io/products/web-api/scrape/dedicated-scrapers).
* **¿Buscas datos de empresas?** Obtén perfiles estructurados de empresas a partir de una palabra clave con [Company Search](https://developers.oxylabs.io/products/web-api/search/companies).
* **¿Quieres obtener JSON estructurado de cualquier página?** Prueba la función integrada de Web API: [AI Parsing](https://developers.oxylabs.io/products/web-api/scrape/ai-parsing).
* **¿Extraes datos a gran escala o los envías a un 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 tengas que escribir código?** Prueba el servidor oficial de Oxylabs para [MCP](https://developers.oxylabs.io/ai-workflows/mcp) o [Agent Skills](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.
