Rastrear motores de búsqueda AI

Usa /batches más un analizador GEO/AEO (Generative Engine Optimization / Answer Engine Optimization) para consultar un motor de búsqueda AI a gran escala y obtener un JSON estructurado: la respuesta, citas y superficies comerciales como anuncios, tarjetas de compras y módulos de productos. Esta página cubre cómo llamar a /v1/batches y vistas compactas del JSON que recibes de vuelta.

Motores

Cada motor necesita su propio ID de analizador y plantilla de URL. Pasa el analizador una vez a nivel de lote. Codifica la consulta en la URL.

Motor	Analizador	Plantilla de URL	Créditos	Máx. ítems
Google AI Mode	`@olostep/google-aimode-results`	`https://www.google.com/aimode?q={query}`	3	2500
Google AI Overview	`@olostep/google-ai-overview-results`	`https://www.google.com/search?q={query}`	3	2500
ChatGPT	`@olostep/chatgpt-results`	`https://chatgpt.com/?q={query}`	5	2500
Perplexity	`@olostep/perplexity-results`	`https://www.perplexity.ai/?q={query}`	3	2500
Gemini	`@olostep/gemini-results`	`https://gemini.google.com/?q={query}`	3	2500
Microsoft Copilot	`@olostep/microsoft-copilot-results`	`https://copilot.microsoft.com/chats?q={query}`	3	1000

Los seis soportan geo-segmentación a través del parámetro country del lote (ISO 3166-1 alpha-2). La cobertura por país varía según el analizador — obtén la lista en vivo en lugar de codificarla:

curl "https://api.olostep.com/v1/countries?service=batches&parser=@olostep/google-aimode-results"

Usa un mensaje informativo (qué es la mitocondria) cuando te interesen las citas. Usa un mensaje comercial (mejores auriculares inalámbricos por menos de $200) cuando necesites anuncios, tarjetas de compras o módulos de productos — esas superficies se detectan por intención y se omiten cuando el motor no las muestra.

1. Crea el lote

custom_id debe ser único dentro del lote. country se aplica a cada ítem.

from olostep import Olostep
from urllib.parse import quote_plus

client = Olostep(api_key="YOUR_API_KEY")

queries = [
    "qué es la mitocondria",
    "mejores auriculares inalámbricos por menos de $200",
]

batch = client.batches.create(
    urls=[
        {
            "custom_id": f"aimode-{i}",
            "url": f"https://www.google.com/aimode?q={quote_plus(q)}",
        }
        for i, q in enumerate(queries, start=1)
    ],
    parser="@olostep/google-aimode-results",
    country="US",
)

print(batch.id, batch.status)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_API_KEY' })

const queries = [
  'qué es la mitocondria',
  'mejores auriculares inalámbricos por menos de $200',
]

const batch = await client.batches.create(
  queries.map((q, i) => ({
    customId: `aimode-${i + 1}`,
    url: `https://www.google.com/aimode?q=${encodeURIComponent(q)}`,
  })),
  {
    parser: '@olostep/google-aimode-results',
    country: 'US',
  }
)

console.log(batch.id, batch.status)

curl -X POST "https://api.olostep.com/v1/batches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parser": { "id": "@olostep/google-aimode-results" },
    "country": "US",
    "items": [
      {
        "custom_id": "aimode-1",
        "url": "https://www.google.com/aimode?q=qué%20es%20la%20mitocondria"
      },
      {
        "custom_id": "aimode-2",
        "url": "https://www.google.com/aimode?q=mejores%20auriculares%20inalámbricos%20por%20menos%20de%20%24200"
      }
    ]
  }'

Para apuntar a un motor diferente, mantén la misma forma de items y cambia parser.id más el host en cada URL. Un lote = un analizador.

El tiempo de procesamiento es aproximadamente constante sin importar el tamaño del lote (típicamente 5–8 minutos). Pasa webhook al crear para obtener batch.completed en lugar de hacer polling. Las cuentas nuevas están limitadas a 100 ítems por lote — contacta a info@olostep.com para aumentarlo.

2. Espera a la finalización

Haz polling a GET /v1/batches/{batch_id} hasta que status sea completed, o maneja el webhook.

import time
import requests

headers = {"Authorization": f"Bearer {API_KEY}"}

def wait_for_batch(batch_id):
    while True:
        info = requests.get(
            f"https://api.olostep.com/v1/batches/{batch_id}",
            headers=headers,
        ).json()
        if info["status"] == "completed":
            return info
        time.sleep(15)

async function waitForBatch(batchId) {
  while (true) {
    const res = await fetch(`https://api.olostep.com/v1/batches/${batchId}`, {
      headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` },
    })
    const info = await res.json()
    if (info.status === 'completed') return info
    await new Promise((r) => setTimeout(r, 15000))
  }
}

curl "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

Los SDKs de Python y Node pueden esperar por ti: itera batch.items() / for await (const item of batch.items()) y bloquean hasta que el lote termine.

3. Recupera `json_content`

Lista los ítems, luego recupera JSON para cada retrieve_id. La carga útil GEO es el objeto analizado dentro de json_content (una cadena JSON — analízala).

import json
import requests

headers = {"Authorization": f"Bearer {API_KEY}"}

items = requests.get(
    f"https://api.olostep.com/v1/batches/{batch_id}/items",
    headers=headers,
).json()["items"]

for item in items:
    payload = requests.get(
        "https://api.olostep.com/v1/retrieve",
        headers=headers,
        params={"retrieve_id": item["retrieve_id"], "formats": "json"},
    ).json()
    data = json.loads(payload["json_content"])
    print(item["custom_id"], data.get("prompt"), len(data.get("sources") or []))

const itemsRes = await fetch(
  `https://api.olostep.com/v1/batches/${batchId}/items`,
  { headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` } }
)
const { items } = await itemsRes.json()

for (const item of items) {
  const params = new URLSearchParams({
    retrieve_id: item.retrieve_id,
    formats: 'json',
  })
  const payload = await fetch(
    `https://api.olostep.com/v1/retrieve?${params}`,
    { headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` } }
  ).then((r) => r.json())

  const data = JSON.parse(payload.json_content)
  console.log(item.custom_id, data.prompt, (data.sources || []).length)
}

for item in batch.items():
    content = item.retrieve(["json"])
    print(item.custom_id, content.json_content)

Los ítems fallidos se listan por separado — pasa status=failed en GET /v1/batches/{batch_id}/items. El JSON alojado también está disponible en json_hosted_url en la carga útil de recuperación por unos 7 días.

Lo que recibes de vuelta

Cada analizador devuelve answer_markdown. La mayoría también devuelve prompt. El resto es específico del motor. Las vistas compactas a continuación son de lotes en vivo country=US.

Los motores listados aquí son los analizadores GEO públicos. También soportamos analizadores adicionales y conectores internamente, además de analizadores personalizados para sitios específicos — los compartimos a pedido. Envía un correo a info@olostep.com o contáctanos en Slack.

Las citas están en sources (cited: true cuando se hace referencia en línea). Las secciones estructuradas están en text_blocks (text, heading, list, table). Las tarjetas patrocinadas están en ads cuando Google las muestra — una consulta en vivo sobre auriculares devolvió fuentes y una tabla de comparación pero omitió ads. Los campos vacíos se eliminan, no se devuelven como [].

{
  "answer_markdown": "Cuando buscas los mejores auriculares inalámbricos supraaurales o circumaurales por menos de $200...",
  "sources": [
    {
      "url": "https://www.reddit.com/r/HeadphoneAdvice/comments/173hvu2/best_wireless_headphones_for_under_200_dollars/",
      "title": "Mejores auriculares inalámbricos por menos de 200 dólares : r/HeadphoneAdvice",
      "description": "Según un usuario de Reddit, los auriculares Sennheiser Accentum son una buena opción...",
      "domain": "https://www.reddit.com",
      "cited": false
    }
  ],
  "text_blocks": [
    { "type": "text", "snippet": "Cuando buscas los mejores auriculares inalámbricos supraaurales o circumaurales por menos de $200..." },
    {
      "type": "table",
      "snippet": "Modelo | Mejor Para | Características Clave | Rango de Precio",
      "data": {
        "headers": ["Modelo", "Mejor Para", "Características Clave", "Rango de Precio"],
        "rows": [
          ["Anker Soundcore Space Q45", "Valor General & ANC", "Fuerte ANC adaptativo, batería de 50 horas", "~$100 - $150"]
        ]
      }
    }
  ]
}

Las fichas en línea son inline_references. El cajón de fuentes es sources. Compras es products. Los bloques de marca patrocinados son ads (brand + cards). Los módulos vacíos son []. network_search_calls es el rastro de búsqueda web.

{
  "url": "https://chatgpt.com/?q=mejores%20auriculares%20inalámbricos%20por%20menos%20de%20%24200",
  "prompt": "mejores auriculares inalámbricos por menos de $200",
  "answer_markdown": "Si te refieres a **auriculares inalámbricos supraaurales con ANC**...",
  "inline_references": [
    {
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "text": "Los 5 Mejores Auriculares por Menos de $200 de 2026 - RTINGS.com",
      "position": 1
    }
  ],
  "sources": [
    {
      "url": "https://www.tomsguide.com/us/best-headphones-deals,news-28645.html",
      "title": "Mejores ofertas de auriculares para agosto de 2026",
      "snippet": "Este resumen de ofertas de auriculares de agosto de 2026...",
      "cited": false,
      "date_published": "2026-08-19T16:18:38.000Z",
      "attribution": "www.tomsguide.com"
    }
  ],
  "ads": [
    {
      "brand": { "name": "Razer", "url": "https://www.razer.com/" },
      "cards": [
        {
          "title": "Razer BlackShark V3 Pro",
          "body": "Los profesionales juran por su claridad inigualable...",
          "url": "https://www.razer.com/gaming-headsets/razer-blackshark-v3-pro?utm_source=chatgpt&...",
          "image": "https://bzrcdn.openai.com/fe8bef58c7129858.jpg"
        }
      ]
    }
  ],
  "products": [
    {
      "title": "Soundcore Space Q45",
      "price": 139.99,
      "currency": "$",
      "vendors": [
        {
          "price": 139.99,
          "currency": "$",
          "website": "Best Buy",
          "link": "https://www.bestbuy.com/product/soundcore-by-anker-space-q45-...?utm_source=chatgpt.com"
        }
      ]
    }
  ],
  "locations": [],
  "web_searched": true,
  "network_search_calls": {
    "search_triggered": true,
    "model_slug": "auto",
    "search_queries": [
      { "query": "mejores auriculares inalámbricos por menos de $200 2026 Sony WH-CH720N Soundcore Space Q45...", "type": "model_query" }
    ]
  }
}

shopping_cards, videos, images, hotels, y places son arreglos vacíos cuando ese módulo no se mostró. search_model_queries es lo que Perplexity realmente buscó.

{
  "url": "https://www.perplexity.ai/search/53051455-01ac-48a2-8aa7-45e518588af0",
  "prompt": "mejores auriculares inalámbricos por menos de $200",
  "answer_markdown": "*   Anker Soundcore Space Q45 Wireless...",
  "sources": [
    {
      "position": 1,
      "label": "Los 5 Mejores Auriculares por Menos de $200 de 2026",
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "description": "",
      "domain": "www.rtings.com",
      "date": ""
    }
  ],
  "related_queries": [
    "mejores auriculares inalámbricos económicos por menos de 200 dólares para calidad de sonido"
  ],
  "shopping_cards": [],
  "videos": [],
  "images": [],
  "hotels": [],
  "places": [],
  "search_model_queries": [
    { "query": "mejores auriculares inalámbricos por menos de $200", "engine": "web", "limit": 8 }
  ],
  "model": "perplexity",
  "web_searched": true
}

text_blocks es la vista general dividida en párrafos y listas. sources son las citas AIO. organic_results es el SERP clásico debajo, cuando está presente.

{
  "url": "https://www.google.com/search?q=qué+es+la+mitocondria&gl=us",
  "prompt": "qué es la mitocondria",
  "answer_markdown": "mitocondria\n\nLas mitocondrias son orgánulos unidos a la membrana...",
  "sources": [
    {
      "title": "La Mitocondria",
      "url": "https://www.youtube.com/watch?v=sl6RXHnAMVs&t=7",
      "source": "YouTube",
      "index": 1
    }
  ],
  "text_blocks": [
    { "type": "paragraph", "snippet": "mitocondria\n\nLas mitocondrias son orgánulos unidos a la membrana..." }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "Mitocondria",
      "link": "https://www.genome.gov/genetics-glossary/Mitochondria",
      "snippet": "Las mitocondrias son orgánulos celulares unidos a la membrana..."
    }
  ]
}

{
  "url": "https://gemini.google.com/app/d11cddf049763b9b",
  "prompt": "mejores auriculares inalámbricos por menos de $200",
  "answer_markdown": "Encontrar grandes auriculares inalámbricos por menos de $200...",
  "sources": [
    {
      "position": 1,
      "label": "Mejores Auriculares con Cancelación de Ruido por menos de $200 (¡50+ Probados!)",
      "url": "https://recordingnow.com/blog/best-budget-wireless-headphones/",
      "description": "El Sony WH-CH720N es el más ligero de tamaño completo...",
      "confidence_level": 9
    }
  ],
  "links_attached": true,
  "model": "gemini"
}

sources[].position es un desplazamiento de carácter en answer_markdown, no un rango. cited es si la fuente está adjunta en la respuesta.

{
  "url": "https://copilot.microsoft.com/chats?q=mejores%20auriculares%20inalámbricos%20por%20menos%20de%20%24200",
  "prompt": "mejores auriculares inalámbricos por menos de $200",
  "answer_markdown": "**Los mejores auriculares inalámbricos por menos de $200 en 2026 son los Sony WH-CH720N...",
  "sources": [
    {
      "url": "https://progressiveradionetwork.com/best-wireless-headphones-under-200-dollars/",
      "title": "10 Mejores Auriculares Inalámbricos por Menos de 200$ (Agosto 2026) Probados",
      "position": 1124,
      "icon_url": "https://services.bingapis.com/favicon?url=progressiveradionetwork.com",
      "cited": true
    }
  ]
}

Ejemplos

Rastrear motores de búsqueda AI

Motores

1. Crea el lote

2. Espera a la finalización

3. Recupera `json_content`

Lo que recibes de vuelta

Relacionado

​Motores

​1. Crea el lote

​2. Espera a la finalización

​3. Recupera json_content

​Lo que recibes de vuelta

​Relacionado

Motores

1. Crea el lote

2. Espera a la finalización

3. Recupera `json_content`

Lo que recibes de vuelta

Relacionado