Lookup

POST /v2/lookup ejecuta una búsqueda web en una de seis categorías y devuelve una lista de resultados plana e independiente del proveedor. Define perceive_top y además renderiza las URL de los N primeros resultados en un navegador real, de modo que un agente obtiene la página de resultados del motor de búsqueda (SERP) y el contenido de la página detrás de cada acierto en una sola ida y vuelta. Es la respuesta de EnConvert a Firecrawl /search: una sola llamada donde, de otro modo, tendrías que invocar una API de búsqueda, analizar sus resultados y luego desplegar un scraper.

Serper la respalda hoy. La petición y la respuesta hablan un vocabulario de búsqueda neutral — category, country, locale, time_filter — de modo que un futuro cambio de proveedor no altera el contrato contra el que programas.

Aquí tienes la llamada útil más pequeña. Envía una consulta y recupera los mejores resultados web:

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "headless chrome pdf rendering"
  }'

La respuesta es una lista de resultados plana más la procedencia para correlación de soporte:

{
    "lookup_id": 81423,
    "query": "headless chrome pdf rendering",
    "category": "web",
    "total": 10,
    "results": [
        {
            "title": "Generate PDFs with headless Chrome",
            "url": "https://example.com/guide/chrome-pdf",
            "snippet": "Render a page and print it to PDF...",
            "position": 1
        },
        {
            "title": "Print to PDF — Chrome DevTools Protocol",
            "url": "https://example.dev/cdp/print-to-pdf",
            "snippet": "Page.printToPDF returns base64 PDF data...",
            "position": 2
        }
    ],
    "perceive_top": 0,
    "perceive_operation_ids": [],
    "credits": 1,
    "cost_cents": 0.06,
    "warnings": []
}

Conviene señalarlo de entrada. /v2/lookup es un endpoint V2 con su propio contador de cuota, lookup_queries, separado de las conversiones V1 y del contador de perceive. Los planes de conversión V1 no incluyen consultas de lookup — necesitas un plan que incluya V2 para llamarlo. Consulta la página de precios para las asignaciones por nivel, y la visión general de V2 para saber cómo se relacionan los contadores de V2.

Endpoints

/v2/lookup es un endpoint de una sola llamada — no hay una ruta separada de estado o recuperación. Cuando auto-percibes, cada página renderizada se convierte en una operación perceive de primera clase con su propio operation_id, que puedes volver a recuperar más tarde mediante GET /v2/perceive/{operation_id}.

Content-Type: application/json.

Autenticación

Autentícate con una clave privada en la cabecera X-API-Key para llamadas servidor a servidor. Esta es la vía que usan los ejemplos siguientes.

X-API-Key: sk_live_your_private_key

Las claves públicas con un token bearer JWT también funcionan, usando el mismo flujo que cualquier otro endpoint — genera un token con tu clave pk_ y luego envíalo como Authorization: Bearer <token>. El flujo completo, incluyendo el bloqueo de dominio y la renovación de tokens, está en la guía de autenticación.

Cada clave de API lleva una lista de permitidos de endpoints. Si /v2/lookup no está en la lista de la clave, la petición se rechaza con 403.

Cómo funciona lookup

Una petición ejecuta una búsqueda del proveedor y — solo si lo pides — renderiza los mejores resultados después.

1. Control de cuota. Antes de facturar nada, el handler comprueba el contador lookup_queries de tu plan. Un plan deshabilitado o una cuota mensual agotada se rechazan con 402, así que no se cobra nada en un rechazo.
2. Búsqueda. La consulta va al proveedor de búsqueda (Serper hoy) en el endpoint correspondiente a tu category. La actualidad, el país, la configuración regional, la ubicación, el tamaño de página y el autocorrector se mapean sobre los parámetros del proveedor.
3. Normalización. Cada acierto del proveedor se aplana en un LookupResult neutral — title, url, snippet, position, y los extras específicos de la categoría aterrizan en extra para que el contrato nunca crezca una columna por cada peculiaridad de proveedor.
4. Cobro y auditoría. La búsqueda tuvo éxito, así que se consume un lookup_queries y se escribe una fila de auditoría ch_lookup_queries. El id de la fila vuelve como lookup_id para correlación de soporte.
5. Auto-perceive (opcional). Si perceive_top > 0, las URL de los N primeros resultados se renderizan de una en una a través del singleton compartido de Chrome headless — el mismo pipeline que el endpoint perceive. Cada renderizado es una operación completa de /v2/perceive: su propio decremento de cuota, su propia fila de operación, su propio operation_id. Las peticiones de auto-perceive solicitan únicamente Markdown — sin captura de pantalla, PDF ni extracción con LLM.

Auto-perceive funciona en modo de mejor esfuerzo. Una sola URL que falla, o la cuota de perceive que se agota a mitad de camino, degrada a una advertencia y aun así devuelve los resultados de búsqueda — la SERP es el producto principal aquí, así que un problema de percepción nunca hunde la llamada entera.

Parámetros de la petición

Consulta y categoría

Segmentación y actualidad

Paginación

Auto-perceive

Categorías

Cada categoría llega a un endpoint distinto del proveedor y expone una forma de resultado ligeramente diferente. Los campos universales (title, url, snippet, position) siempre están tipados; los campos específicos de la categoría aterrizan en extra.

Conviene señalar: para images y maps, url puede ser null en un acierto dado cuando el proveedor no devuelve un enlace navegable. Auto-perceive omite cualquier resultado cuya url sea null, así que un perceive_top de 5 sobre una SERP con dos aciertos sin URL percibe como mucho tres páginas.

Respuesta

El endpoint omite los campos null, así que un resultado web mínimo lleva solo los campos que realmente están poblados.

LookupResult

Leer los resultados de auto-perceive

Cuando envías perceive_top, recorre los resultados y comprueba el campo perceive — está presente solo en los resultados que se percibieron, y solo cuando su renderizado tuvo éxito. El Markdown de cada uno vive detrás de una URL de descarga prefirmada (un enlace firmado y de corta duración al almacenamiento de objetos) bajo perceive.outputs.markdown.url, igual que en una llamada directa a perceive.

{
    "lookup_id": 81910,
    "query": "react server components data fetching",
    "category": "web",
    "total": 10,
    "results": [
        {
            "title": "Data fetching with RSC",
            "url": "https://example.com/rsc/data",
            "snippet": "Fetch on the server, stream to the client...",
            "position": 1,
            "perceive": {
                "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
                "status": "completed",
                "url": "https://example.com/rsc/data",
                "outputs": {
                    "markdown": {
                        "url": "https://spaces.example.com/...signed...",
                        "size_bytes": 7421,
                        "content_type": "text/markdown; charset=utf-8",
                        "expires_in": 900
                    }
                },
                "cost_cents": 0.0,
                "duration_ms": 5840
            }
        }
    ],
    "perceive_top": 1,
    "perceive_operation_ids": [
        "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7"
    ],
    "credits": 1,
    "cost_cents": 0.06,
    "warnings": []
}

Esas URL firmadas expiran tras 15 minutos. Para descargar una página percibida más tarde, vuelve a recuperar su operación con GET /v2/perceive/{operation_id} usando el id de perceive_operation_ids — eso vuelve a firmar las URL y no vuelve a renderizar, así que no cuesta cuota. Consulta la sección de recuperación de perceive para los detalles.

Ejemplos de código

curl — búsqueda web

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "open source vector database",
    "num_results": 20
  }'

curl — noticias recientes, localizadas

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rbi monetary policy",
    "category": "news",
    "country": "in",
    "locale": "en",
    "time_filter": "week"
  }'

curl — búsqueda más auto-perceive de los 3 primeros

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "langchain retrieval augmented generation",
    "perceive_top": 3
  }'

Python

import requests

response = requests.post(
    "https://api.enconvert.com/v2/lookup",
    headers={"X-API-Key": "sk_live_your_private_key"},
    json={
        "query": "langchain retrieval augmented generation",
        "perceive_top": 3,
    },
)
response.raise_for_status()
data = response.json()

# Pull the Markdown of every result that was perceived
for result in data["results"]:
    perceived = result.get("perceive")
    if not perceived:
        continue
    markdown_url = perceived["outputs"]["markdown"]["url"]
    page_text = requests.get(markdown_url).text
    print(result["url"], len(page_text), "chars")

for note in data["warnings"]:
    print("warning:", note)

Node.js

const res = await fetch("https://api.enconvert.com/v2/lookup", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_live_your_private_key"
    },
    body: JSON.stringify({
        query: "langchain retrieval augmented generation",
        perceive_top: 3
    })
});

const data = await res.json();

// Pull the Markdown of every result that was perceived
for (const result of data.results) {
    if (!result.perceive) continue;
    const markdownUrl = result.perceive.outputs.markdown.url;
    const pageText = await fetch(markdownUrl).then(r => r.text());
    console.log(result.url, pageText.length, "chars");
}

for (const note of data.warnings) {
    console.log("warning:", note);
}

Si llamas a EnConvert desde Claude, Cursor u otro cliente del Model Context Protocol (MCP), la capacidad de búsqueda se expone como una herramienta — consulta la página del servidor MCP.

Restricciones por plan

Las consultas de lookup se miden en su propio contador, lookup_queries, separado de las conversiones V1 y del contador de perceive que usa el endpoint perceive. Los planes de conversión V1 no incluyen cuota de lookup; necesitas un plan que incluya V2.

Dos cosas se facturan de forma independiente en una llamada de lookup:

Así que una llamada con perceive_top: 3 consume un lookup_queries y hasta tres perceive_operations. Si tu cuota de perceive se agota a mitad del bucle, la búsqueda aun así devuelve — auto-perceive simplemente se detiene en el límite y lo anota en warnings, en lugar de hacer fallar la petición entera.

Las asignaciones por nivel para ambos contadores están en la página de precios; se configuran por plan, no están codificadas en duro en el endpoint. (En el momento de escribir esto, el plan Free trae por defecto 25 lookup_queries y 50 perceive_operations al mes.)

Respuestas de error

El handler nunca repite el texto crudo del proveedor al cliente — el detalle del proveedor y de SSRF se queda en los logs del servidor, y el cliente recibe un mensaje limpio y genérico.

Un auto-perceive que falla nunca lanza un error propio — aterriza en warnings y la llamada aun así responde 200. La referencia completa de códigos de estado está en la guía de códigos de error.

Límites