> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Lookup: mira cómo muestran un producto los motores de compra con IA

> Pregunta a ChatGPT, Google AI Overviews, AI Mode, Copilot y Naver AI Tab por un producto y comprueba, motor por motor, si la respuesta lo mostró, qué ofertas de comercios usó y qué páginas citó.

Usa Product Lookup para ver un producto tal como los motores de compra con IA se lo muestran a los compradores. Envía el nombre de un producto y un mercado, y querying.ai pregunta por él a cada motor. Para cada motor sabrás si la respuesta mostró el producto, qué ofertas de comercios mostró (comercio, catálogo, precio, stock, valoración y número de reseñas) y qué páginas cita. Añade hasta cinco competidores para compararlos motor por motor, y hasta tres prompts de compra, como `best moisturizing eye cream`, para ver cuáles de estos productos muestra cada motor a un comprador.

Con una consulta sabrás, por ejemplo:

* Si ChatGPT, Google AI Overviews, AI Mode o Copilot muestran el producto cuando se les pregunta por él.
* De qué comercios y registros de catálogo lo muestra cada motor, a qué precio, con qué valoración y cuántas reseñas.
* Qué leyó sobre el producto el modelo que responde en ChatGPT.
* Cómo queda el producto frente a sus competidores en cada motor.
* Cuáles de estos productos muestra cada motor ante una búsqueda de compra.

## Enviar una consulta

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/product-lookup \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "belif Moisturizing Eye Bomb",
    "country": "US",
    "competitors": ["Clinique All About Eyes", "CeraVe Eye Repair Cream"],
    "prompts": ["best eye cream for puffiness", "best moisturizing eye cream"],
    "idempotencyKey": "eye-bomb-us"
  }'
```

La consulta se divide en preguntas: cada pregunta es una petición a un motor sobre un producto o un prompt. Cada pregunta entra en cola como una tarea normal, y la respuesta de la API las enumera. Aquí aparece recortada a tres de las 23 preguntas:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": {
    "id": "eye-bomb-us",
    "product": "belif Moisturizing Eye Bomb",
    "competitors": ["Clinique All About Eyes", "CeraVe Eye Repair Cream"],
    "prompts": ["best eye cream for puffiness", "best moisturizing eye cream"],
    "country": "US",
    "engines": ["CHATGPT", "GOOGLE", "AIMODE", "BING_COPILOT"]
  },
  "summary": { "total": 23, "succeeded": 23, "failed": 0 },
  "credits": { "creditsToCharge": 40, "creditsCharged": 0 },
  "asks": [
    {
      "engine": "CHATGPT",
      "taskType": "CHATGPT",
      "role": "product",
      "prompt": "Buy belif Moisturizing Eye Bomb",
      "success": true,
      "task": {
        "id": "56be57f3-d316-4727-8bd3-ab065fed2ec1",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:22:43.422Z",
        "idempotencyKey": "eye-bomb-us:CHATGPT:buy"
      }
    },
    {
      "engine": "CHATGPT",
      "taskType": "CHATGPT",
      "role": "competitor",
      "prompt": "Buy Clinique All About Eyes",
      "success": true,
      "task": {
        "id": "35f300a4-7603-4ad0-97ba-82eb6a07eed9",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:22:43.637Z",
        "idempotencyKey": "eye-bomb-us:CHATGPT:buy:c1"
      }
    },
    {
      "engine": "AIMODE",
      "taskType": "AIMODE",
      "role": "prompt",
      "query": "best eye cream for puffiness",
      "success": true,
      "task": {
        "id": "bff41168-d081-4bce-a873-9609baafbaa5",
        "taskType": "AIMODE",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:22:44.149Z",
        "idempotencyKey": "eye-bomb-us:AIMODE:p1"
      }
    }
  ]
}
```

* `lookup.id` es tu `idempotencyKey`, o un UUID que elige el servidor si no envías ninguno. Con él lees la consulta.
* Cada entrada de `asks[]` tiene su `role` (`product`, `competitor` o `prompt`), el texto preguntado en `prompt` o `query`, y su `task`. Una pregunta rechazada tiene `success: false` y un `error` en lugar de `task`. Consulta [Errores](#errores).
* `credits.creditsToCharge` suma los precios de las preguntas que devuelve la API, retenidos de tu saldo hasta que termina cada pregunta. `creditsCharged` es lo que ya se les ha cobrado.

Lee la consulta con `GET /v1/product-lookup/{id}` hasta que `lookup.status` sea `COMPLETED`. Esta consulta tardó unos dos minutos; una consulta termina cuando responde su motor más lento. Con `webhook.url`, recibes la tarea de cada pregunta cuando termina, con la clave de la pregunta en `task.idempotencyKey`, que empieza por el id de la consulta. Ningún webhook cubre la consulta entera, así que lee la consulta en cada entrega y comprueba `lookup.status`. Los esquemas están en la referencia de la API: [Product Lookup](/es/api-reference/product-lookup.md) y [Obtener un Product Lookup](/es/api-reference/get-product-lookup.md).

## Campos de la solicitud

| Campo | Obligatorio | Descripción |
| - | - | - |
| `product` | Sí | El nombre del producto tal como lo escriben los compradores, de 1 a 200 caracteres, como `belif Moisturizing Eye Bomb`. Una URL de página de producto o un GTIN devuelve `400 VALIDATION_ERROR`. |
| `country` | Sí | `US` (Estados Unidos) o `KR` (Corea del Sur), sin distinguir mayúsculas. Cualquier otro valor devuelve `422 REGION_UNSUPPORTED`. |
| `competitors` | No | Hasta 5 nombres de otros productos, con las reglas de `product`. A cada uno se le hacen las mismas preguntas que al producto. Un nombre igual al del producto, o repetido, devuelve `400`. Los nombres que solo difieren en mayúsculas, puntuación o espacios cuentan como iguales. |
| `prompts` | No | Hasta 3 prompts de compra de 1 a 300 caracteres, como `best moisturizing eye cream`. Cada uno se pregunta una vez a cada motor, tal como está escrito. |
| `engines` | No | Los motores a los que preguntar: `CHATGPT`, `GOOGLE`, `AIMODE`, `BING_COPILOT`, `GEMINI`, y `NAVER_AI_TAB` solo en `KR`. Por defecto, los motores del mercado que se indican más abajo. |
| `idempotencyKey` | No | Da nombre a la consulta: de 1 a 200 caracteres, sin espacios al principio ni al final. Consulta [Volver a enviar una consulta](#volver-a-enviar-una-consulta). |
| `priority` | No | Entero de `1` a `10`, `1` por defecto, que se aplica a cada pregunta. Los valores fuera de rango se ajustan al límite. No garantiza el orden de ejecución. |
| `webhook.url` | No | Recibe la tarea de cada pregunta cuando termina. Consulta [Webhooks](/es/concepts/webhooks.md). |

## Motores y preguntas

El producto y cada competidor reciben las mismas preguntas:

| Motor | `US` | `KR` |
| - | - | - |
| `CHATGPT` | `Buy {product}` y `Find the best price for {product}` | `{product} 구매` y `{product} 최저가` |
| `GOOGLE` (AI Overviews) | El nombre del producto | El nombre del producto, si lo pides |
| `AIMODE` (AI Mode) | El nombre del producto | El nombre del producto |
| `BING_COPILOT` (Copilot) | El nombre del producto | El nombre del producto, si lo pides |
| `NAVER_AI_TAB` (Naver AI Tab) | No disponible | El nombre del producto |
| `GEMINI` | El nombre del producto, si lo pides | El nombre del producto, si lo pides |

"Si lo pides" significa que a ese motor solo se le pregunta cuando lo incluyes en `engines`. Sin `engines`, una consulta en `US` pregunta a ChatGPT, AI Overviews, AI Mode y Copilot, es decir, 5 preguntas por producto. Una consulta en `KR` pregunta a Naver AI Tab, ChatGPT y AI Mode, 4 preguntas por producto. Un prompt de compra se pregunta una vez a cada motor: 4 preguntas con los motores por defecto de `US` y 3 con los de `KR`. La consulta de arriba hizo 3 × 5 + 2 × 4 = 23 preguntas.

A ChatGPT se le hacen dos preguntas porque una sola muestra un registro del producto en aproximadamente la mitad de los productos, y la misma pregunta repetida suele dar con otra mitad. Los demás motores por defecto son los que mostraron productos en una prueba con 50 productos el 2026-10-20:

| Motor | `US` | `KR` |
| - | - | - |
| ChatGPT, las dos preguntas, con tarjetas de widget | 24 de 24 consultas | 20 de 20 consultas |
| Copilot | 25 de 25 | 0 de 25 |
| Google AI Overviews | 23 de 25 | 1 de 25 |
| Google AI Mode | 23 de 25 | 13 de 25 |
| Naver AI Tab | – | 25 de 25 |

La fila de ChatGPT sale de 12 productos de `US` y 10 de `KR`, consultados dos veces cada uno. Gemini no mostró ningún registro de producto en 115 preguntas entre los dos mercados.

## Leer la consulta

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/product-lookup/eye-bomb-us \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

El resultado tiene cinco partes:

* `lookup`: qué se preguntó, su `status` y los `credits` cobrados hasta ahora.
* `summary` y `engines[]`: las respuestas sobre el producto, en conjunto y motor por motor.
* `competitors[]`: los mismos `summary` y `engines[]` para cada competidor.
* `comparison[]`: el producto y sus competidores lado a lado, motor por motor.
* `prompts[]`: lo que respondió cada motor a cada prompt de compra.

`lookup.status` es `QUEUED` hasta que empieza alguna pregunta y `PROCESSING` mientras quede alguna sin terminar. Pasa a `COMPLETED` cuando todas las preguntas han terminado y al menos una se completó, y a `FAILED` cuando fallaron todas. Las entradas se van llenando a medida que terminan las preguntas, así que puedes leer una consulta antes de que se complete.

Aquí están `lookup`, `summary` y `engines[]` de la consulta de arriba, recortados a dos de los cuatro motores y a unas pocas entradas por lista:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": {
    "id": "eye-bomb-us",
    "product": "belif Moisturizing Eye Bomb",
    "competitors": ["Clinique All About Eyes", "CeraVe Eye Repair Cream"],
    "prompts": ["best eye cream for puffiness", "best moisturizing eye cream"],
    "country": "US",
    "status": "COMPLETED",
    "createdAt": "2026-10-20T09:22:43.422Z",
    "completedAt": "2026-10-20T09:24:36.695Z",
    "credits": 40
  },
  "summary": {
    "foundIn": ["CHATGPT", "GOOGLE", "AIMODE", "BING_COPILOT"],
    "notFoundIn": [],
    "pending": [],
    "failed": [],
    "merchants": [
      {
        "merchant": "Ulta Beauty",
        "engines": ["CHATGPT", "BING_COPILOT"],
        "price": { "currency": "USD", "min": 48, "max": 48 }
      },
      {
        "merchant": "Amazon",
        "engines": ["CHATGPT"],
        "price": { "currency": "USD", "min": 43, "max": 43 }
      },
      {
        "merchant": "Comparor",
        "engines": ["BING_COPILOT"],
        "price": { "currency": "USD", "min": 35.82, "max": 45.9 }
      }
    ],
    "priceRange": { "currency": "USD", "min": 35.82, "max": 48 },
    "citedDomains": [
      { "domain": "ulta.com", "engines": ["CHATGPT", "GOOGLE", "AIMODE", "BING_COPILOT"] },
      { "domain": "lgbeauty.com", "engines": ["CHATGPT", "GOOGLE", "AIMODE"] }
    ],
    "credits": 10
  },
  "engines": [
    {
      "engine": "CHATGPT",
      "status": "COMPLETED",
      "found": true,
      "via": [
        {
          "taskType": "CHATGPT",
          "prompt": "Buy belif Moisturizing Eye Bomb",
          "taskId": "56be57f3-d316-4727-8bd3-ab065fed2ec1",
          "status": "COMPLETED",
          "completedAt": "2026-10-20T09:23:04.711Z",
          "credits": 2
        },
        {
          "taskType": "CHATGPT",
          "prompt": "Find the best price for belif Moisturizing Eye Bomb",
          "taskId": "c60ffa61-d399-4b15-8343-452dcc150fd3",
          "status": "COMPLETED",
          "completedAt": "2026-10-20T09:23:20.863Z",
          "credits": 2
        }
      ],
      "listings": [
        {
          "position": 1,
          "title": "belif Moisturizing Eye Bomb Eye Cream",
          "source": "merchant_feed",
          "merchant": "Ulta Beauty",
          "url": "https://www.ulta.com/p/moisturizing-eye-bomb-eye-cream-pimprod2043262?cmpid…",
          "price": { "value": 48, "currency": "USD", "raw": "$48.00" },
          "available": true,
          "brand": "belif",
          "modelSees": {
            "title": "belif Moisturizing Eye Bomb Eye Cream",
            "description": "belif's Moisturizing Eye Bomb Eye Cream is a lightweight cream that floods the eye area wi…",
            "rating": 4.5,
            "reviewCount": 105,
            "brand": "belif"
          },
          "ids": { "chatgptProductId": "2619879", "feedId": "oai-shopping-id:v1:feed:…" },
          "ask": 1,
          "match": { "score": 1 }
        },
        {
          "position": 1,
          "title": "Amazon",
          "source": "chatgpt_widget",
          "merchant": "Amazon",
          "url": "https://www.amazon.com/s?k=belif+Moisturizing+Eye+Bomb",
          "price": { "value": 43, "currency": "USD", "raw": "$43.00" },
          "description": "Reported sale price · $5 below retail · A recent October 2026 deal report lists this price.",
          "pictured": "belif Moisturizing Eye Bomb 25ml blue jar white lid",
          "ask": 2,
          "match": { "score": 1 }
        }
      ],
      "otherListings": [],
      "citedPages": [
        {
          "url": "https://lgbeauty.com/products/moisturizing-eye-bomb?selectedVariant=47584416432448",
          "domain": "lgbeauty.com",
          "title": "Moisturizing Eye Bomb",
          "ask": 1
        }
      ]
    },
    {
      "engine": "AIMODE",
      "status": "COMPLETED",
      "found": true,
      "via": [
        {
          "taskType": "AIMODE",
          "query": "belif Moisturizing Eye Bomb",
          "taskId": "74807193-762f-4689-a974-0dfb395ed0f9",
          "status": "COMPLETED",
          "completedAt": "2026-10-20T09:24:30.021Z",
          "credits": 2
        }
      ],
      "listings": [
        {
          "position": 1,
          "title": "belif Moisturizing Eye Bomb",
          "source": "google_shopping",
          "merchant": "Loja Glamourosa",
          "url": "https://www.google.com/search?ibp=oshop&prds=…",
          "price": { "value": 39.59, "currency": "USD", "raw": "$39.59" },
          "oldPrice": { "value": 53, "currency": "USD", "raw": "$53" },
          "rating": 4.7,
          "reviewCount": 1300,
          "ids": {
            "googleProductGroupId": "6991299462534820972",
            "googleCatalogId": "7562423970477224507",
            "googleProductDocId": "5915412989765911473"
          },
          "ask": 1,
          "match": { "score": 1 }
        },
        {
          "position": 2,
          "title": "belif Moisturizing Eye Bomb Stick",
          "source": "google_shopping",
          "merchant": "Oseila Beauty",
          "url": "https://www.google.com/search?ibp=oshop&prds=…",
          "price": { "value": 37.24, "currency": "USD", "raw": "$37.24" },
          "rating": 5,
          "reviewCount": 7,
          "ask": 1,
          "match": { "score": 1, "variant": ["stick"] }
        }
      ],
      "otherListings": [
        {
          "position": 3,
          "title": "belif Aqua Bomb Depuffing Eye Gel",
          "source": "google_shopping",
          "merchant": "Ulta Beauty",
          "price": { "value": 32, "currency": "USD", "raw": "$32.00" },
          "rating": 4.1,
          "reviewCount": 1400,
          "ask": 1,
          "match": { "score": 0.75, "missing": ["moisturizing"] }
        }
      ],
      "citedPages": [
        {
          "url": "https://www.sephora.com/product/belif-moisturizing-eye-bomb-with-peptide-ceramide-P510122",
          "domain": "sephora.com",
          "title": "Sephora",
          "ask": 1
        }
      ]
    }
  ]
}
```

Los cuatro motores mostraron el producto. ChatGPT mostró un registro del feed de productos de Ulta Beauty, y el modelo que responde leyó en él una valoración de 4,5 con 105 reseñas. ChatGPT también escribió tarjetas de widget para tres tiendas, entre ellas Amazon. AI Mode mostró la oferta de un comercio y una versión en barra marcada como `variant`, y puso el gel para el contorno de ojos de la marca en `otherListings`.

### `summary`

| Campo | Descripción |
| - | - |
| `foundIn`, `notFoundIn` | Los motores cuyas respuestas mostraron el producto, y los motores cuyas preguntas terminaron sin mostrarlo. |
| `pending`, `failed` | Los motores con preguntas aún en curso, y los motores en los que fallaron todas las preguntas. |
| `merchants[]` | Cada comercio de las ofertas del producto, con los `engines` que lo mostraron y su rango de `price` por unidad en ellos; primero, los que aparecen en más motores. |
| `priceRange` | Precios por unidad en todos los motores, en la moneda del mercado: USD para `US` y KRW para `KR`. Las ofertas de otro formato o presentación (`match.variant`) quedan fuera. |
| `citedDomains[]` | Cada sitio que citan las respuestas, con los `engines` que lo citan; primero, los citados por más motores. |
| `credits` | Créditos cobrados hasta ahora por las preguntas del producto. `lookup.credits` cubre la consulta entera. |

### `engines[]`

Una entrada por cada motor consultado:

| Campo | Descripción |
| - | - |
| `status` | Las preguntas del motor en conjunto: `QUEUED`, `PROCESSING`, `COMPLETED` cuando todas terminaron y una se completó, o `FAILED` cuando fallaron todas. |
| `found` | `true` cuando una respuesta mostró una oferta del producto, de un registro de catálogo o de una tarjeta de widget de ChatGPT. `false` cuando todas las preguntas terminaron sin ninguna. `null` mientras haya preguntas en curso y todavía no se haya encontrado nada, y cuando fallaron todas las preguntas. |
| `via[]` | Las preguntas del motor en orden, cada una con el texto preguntado, su `taskId`, `status` y `credits`, y el `error` si falló. |
| `listings[]` | Ofertas que se consideran el producto, u otro formato o presentación de él. Una oferta que mostraron dos preguntas aparece una sola vez. |
| `otherListings[]` | Otros productos que mostraron las respuestas. Aquí puede acabar una versión del producto con otro nombre o traducida. |
| `citedPages[]` | Las páginas que citan las respuestas, cada una con `url`, `domain` (el host sin `www.` ni `m.`), `title` y `ask`. En ChatGPT, son las fuentes que cita su respuesta. |

### Campos de una oferta

Una oferta es el registro del producto de un comercio, tal como lo tiene el motor. Solo trae los campos que da el motor.

| Campo | Descripción |
| - | - |
| `position` | Orden en la respuesta, desde 1. |
| `ask` | Qué pregunta del motor la mostró, desde 1, en el orden de `via[]`. |
| `title` | El nombre del producto en el registro. En una tarjeta de widget de ChatGPT, el encabezado de la tarjeta, que puede ser el nombre de la tienda. |
| `merchant` | Quién lo vende. |
| `source` | De dónde viene la oferta. Consulta la tabla siguiente. |
| `url` | La página del comercio cuando el motor la enlaza; si no, la página de producto del propio motor. |
| `price`, `oldPrice` | `value`, `currency` y `raw` tal como se muestra. `currency` es un código ISO 4217 cuando el símbolo no es ambiguo en el mercado. `oldPrice` es el precio antes de un descuento que muestra el motor. |
| `available` | Si hay stock. Solo ChatGPT. |
| `rating`, `reviewCount` | La valoración y el número de reseñas del registro. |
| `modelSees` | Solo ChatGPT: lo que ChatGPT dio al modelo que responde sobre el registro: `title`, `description`, `rating`, `reviewCount`, `brand` y `productPage`. La valoración y el número de reseñas de un registro del feed de un comercio solo están aquí. |
| `image`, `description`, `brand` | Tal como los muestra el motor. |
| `reviews` | El `summary`, los `pros` y los `cons` de las reseñas que muestra el motor. |
| `ids` | Identificadores de catálogo que enlazan los registros de un mismo producto, como `chatgptProductId` y `feedId` en ChatGPT, `googleCatalogId`, `googleProductGroupId` y `googleProductDocId` en los motores de Google, `bingProductId` y `bingGroupId` en Copilot, y `naverProductId` en Naver AI Tab. Ningún motor devuelve un GTIN. |
| `pictured` | En una tarjeta de widget de ChatGPT: lo que muestra la imagen junto a la tarjeta, según la búsqueda que escribió la respuesta para encontrarla. |
| `match` | Por qué la oferta cuenta como el producto. `score` es la proporción de palabras del nombre del producto que aparecen en la oferta, de 0 a 1. `missing` enumera las palabras que no aparecen, `variant` marca otro formato o presentación (set, mini, 1+1, barra) y `accessory` una pieza en lugar del producto, como un filtro de recambio. |

`source` indica de qué catálogo viene una oferta:

| `source` | Motor | Qué es |
| - | - | - |
| `shopify` | ChatGPT | El registro de una tienda Shopify en el catálogo de productos de ChatGPT |
| `merchant_feed` | ChatGPT | Un registro del feed de productos que un comercio envía a ChatGPT |
| `google_shopping` | ChatGPT, AI Overviews, AI Mode, Gemini | Un registro de Google Shopping |
| `chatgpt_catalog` | ChatGPT | Un registro del catálogo de ChatGPT que no indica su origen |
| `chatgpt_widget` | ChatGPT | Una tienda y un precio que ChatGPT escribió en una tarjeta de widget, sin ningún registro detrás |
| `microsoft_shopping` | Copilot | Una oferta de Microsoft Shopping |
| `naver_shopping` | Naver AI Tab | Una oferta de Naver Shopping |

### Tarjetas de widget de ChatGPT

ChatGPT suele responder a una búsqueda de compra con tarjetas; cada una indica una tienda y un precio que leyó en la página de la tienda, sin registro de catálogo detrás. Una consulta lee cada tarjeta como una oferta `chatgpt_widget`, después de los registros de la respuesta, y la cuenta para `found`.

* `merchant` es la tienda que indica la tarjeta, o el dominio de su enlace de compra. `description` es la línea de descripción de la tarjeta.
* Una tarjeta no tiene `rating`, `reviewCount`, `available`, `ids` ni `modelSees`. Con un rango de precios como `$40–$62`, `price` queda fuera.
* No se lee una tarjeta que no tenga ni enlace de compra ni línea de vendedor.
* Se descarta una tarjeta con la misma tienda y el mismo precio que un registro o una tarjeta anterior del producto. Dos tiendas son la misma cuando sus nombres o sus sitios enlazados coinciden, o uno empieza por el otro, como Ulta, Ulta Beauty y ulta.com.

Para leer solo registros de catálogo, deja fuera las ofertas cuyo `source` sea `chatgpt_widget`.

## Comparar con competidores

Una pregunta sobre un producto rara vez muestra el producto de otra marca; en la prueba con 50 productos no ocurrió ni una vez. Por eso eres tú quien indica los competidores, y cada uno recibe las preguntas del producto. Cada entrada de `competitors[]` tiene el `product`, el `summary` y los `engines[]` del competidor, y se lee igual que la del producto.

`comparison[]` alinea el producto y sus competidores, con una fila por producto y una entrada por motor. De la consulta de arriba, recortada a Copilot, más ChatGPT para el producto:

```json theme={"theme":"css-variables"}
{
  "comparison": [
    {
      "product": "belif Moisturizing Eye Bomb",
      "role": "product",
      "engines": [
        {
          "engine": "CHATGPT",
          "status": "COMPLETED",
          "found": true,
          "listings": 4,
          "merchants": 4,
          "mostReviewed": { "reviewCount": 105, "rating": 4.5, "merchant": "Ulta Beauty" },
          "priceRange": { "currency": "USD", "min": 43, "max": 48 },
          "prompts": { "answered": 2, "appeared": 0 }
        },
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "found": true,
          "listings": 6,
          "merchants": 5,
          "mostReviewed": { "reviewCount": 2942, "rating": 4.58, "merchant": "Comparor" },
          "priceRange": { "currency": "USD", "min": 35.82, "max": 48 },
          "prompts": { "answered": 2, "appeared": 1 }
        }
      ]
    },
    {
      "product": "Clinique All About Eyes",
      "role": "competitor",
      "engines": [
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "found": true,
          "listings": 4,
          "merchants": 3,
          "mostReviewed": { "reviewCount": 85773, "rating": 4.6, "merchant": "Walmart" },
          "priceRange": { "currency": "USD", "min": 38.05, "max": 72 },
          "prompts": { "answered": 2, "appeared": 0 }
        }
      ]
    },
    {
      "product": "CeraVe Eye Repair Cream",
      "role": "competitor",
      "engines": [
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "found": true,
          "listings": 6,
          "merchants": 6,
          "mostReviewed": { "reviewCount": 117193, "rating": 4.35, "merchant": "Pasteur Pharmacy" },
          "priceRange": { "currency": "USD", "min": 15.95, "max": 38.95 },
          "prompts": { "answered": 2, "appeared": 0 }
        }
      ]
    }
  ]
}
```

| Campo | Descripción |
| - | - |
| `role` | `product` o `competitor`. |
| `found` | Igual que en `engines[]`. |
| `listings` | Cuántas ofertas se consideran el producto, contando las tarjetas de widget de ChatGPT. |
| `merchants` | Cuántos comercios hay entre esas ofertas. |
| `mostReviewed` | La oferta con más reseñas: su `reviewCount`, `rating` y `merchant`. En ChatGPT, el número que recibió el modelo que responde en `modelSees`. Copilot pone el número de reseñas de un producto en la oferta de cada comercio, así que `merchant` es la primera oferta que lo lleva. |
| `priceRange` | Precios por unidad en ese motor. |
| `prompts` | Solo cuando la consulta tiene prompts de compra: `answered` es cuántos de ellos respondió el motor, y `appeared`, en cuántas de esas respuestas se mostró o se nombró el producto. |

Los tres productos se encontraron en los cuatro motores. En Copilot, la oferta con más reseñas del producto tiene 2.942 reseñas, frente a 85.773 y 117.193 de los dos competidores. En las ocho respuestas a prompts de compra, CeraVe Eye Repair Cream apareció en cinco, y el producto y Clinique All About Eyes en dos cada uno.

## Prompts de compra

Cada entrada de `prompts[]` tiene el `prompt` y una entrada por motor en `engines[]`:

| Campo | Descripción |
| - | - |
| `shown` | Los productos de la consulta, el producto y sus competidores, que la respuesta mostró como registro o tarjeta de widget, en el orden en que aparecen. |
| `named` | Los productos de la consulta que nombra el texto de la respuesta, en el orden en que los nombra. |
| `listings[]` | Cada registro de producto y cada tarjeta de widget de la respuesta. Los que corresponden a un producto de la consulta llevan `product` y `match`. |
| `via[]`, `citedPages[]` | Igual que en `engines[]`. |

La respuesta a un prompt de compra muestra productos de muchas marcas, así que un registro solo cuenta como uno de los productos de la consulta cuando contiene la marca, es decir, la primera palabra del nombre del producto. Un nombre en el texto cuenta igual que un [monitor GEO](/es/monitors.md) cuenta una mención de marca, con el nombre completo del producto como término.

De la consulta de arriba, AI Overviews y Copilot respondiendo a `best moisturizing eye cream`, con las ofertas recortadas a los productos de la consulta:

```json theme={"theme":"css-variables"}
{
  "prompts": [
    {
      "prompt": "best moisturizing eye cream",
      "engines": [
        {
          "engine": "GOOGLE",
          "status": "COMPLETED",
          "via": [
            {
              "taskType": "GOOGLE",
              "query": "best moisturizing eye cream",
              "taskId": "ae6a153a-6382-40d6-84df-c99de0b60d17",
              "status": "COMPLETED",
              "completedAt": "2026-10-20T09:24:29.231Z",
              "credits": 1.25
            }
          ],
          "shown": ["CeraVe Eye Repair Cream", "Clinique All About Eyes"],
          "named": [
            "belif Moisturizing Eye Bomb",
            "CeraVe Eye Repair Cream",
            "Clinique All About Eyes"
          ],
          "listings": [
            {
              "position": 1,
              "title": "CeraVe Eye Repair Cream",
              "source": "google_shopping",
              "product": "CeraVe Eye Repair Cream",
              "match": { "score": 1 }
            },
            {
              "position": 3,
              "title": "Clinique All About Eyes Rich",
              "source": "google_shopping",
              "product": "Clinique All About Eyes",
              "match": { "score": 1 }
            }
          ],
          "citedPages": [
            {
              "url": "https://www.nytimes.com/wirecutter/reviews/best-eye-cream/",
              "domain": "nytimes.com",
              "title": "The New York Times"
            }
          ]
        },
        {
          "engine": "BING_COPILOT",
          "status": "COMPLETED",
          "via": [
            {
              "taskType": "BING_COPILOT",
              "prompt": "best moisturizing eye cream",
              "taskId": "0f582e93-7756-439d-8e5c-bacc510fdff0",
              "status": "COMPLETED",
              "completedAt": "2026-10-20T09:23:45.384Z",
              "credits": 1.25
            }
          ],
          "shown": ["belif Moisturizing Eye Bomb"],
          "named": ["belif Moisturizing Eye Bomb"],
          "listings": [
            {
              "position": 1,
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide",
              "source": "microsoft_shopping",
              "merchant": "Comparor",
              "price": { "value": 45.9, "currency": "USD", "raw": "$45.9" },
              "rating": 4.58,
              "reviewCount": 2942,
              "product": "belif Moisturizing Eye Bomb",
              "match": { "score": 1 }
            },
            {
              "position": 2,
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide",
              "source": "microsoft_shopping",
              "merchant": "SweetCare",
              "price": { "value": 41.36, "currency": "USD", "raw": "$41.36" },
              "rating": 4.58,
              "reviewCount": 2942,
              "product": "belif Moisturizing Eye Bomb",
              "match": { "score": 1 }
            },
            {
              "position": 3,
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide",
              "source": "microsoft_shopping",
              "merchant": "Macy's",
              "price": { "value": 48, "currency": "USD", "raw": "$48" },
              "rating": 4.58,
              "reviewCount": 2942,
              "product": "belif Moisturizing Eye Bomb",
              "match": { "score": 1 }
            }
          ],
          "citedPages": [
            {
              "url": "https://www.comparor.com/us/belif-moisturizing-eye-bomb-hydrating-eye-cream-25ml.html?utm_source=copilot.com",
              "domain": "comparor.com",
              "title": "belif Moisturizing Eye Bomb with Peptide and Ceramide"
            }
          ]
        }
      ]
    }
  ]
}
```

AI Overviews nombró el producto en su texto, pero solo mostró registros de los dos competidores. Copilot mostró el producto en tres comercios. La coincidencia se basa en nombres, así que una versión cuyo nombre añade una palabra, como `Clinique All About Eyes Rich`, cuenta como el producto correspondiente.

## Volver a enviar una consulta

Cada pregunta tiene su propia clave, formada a partir del id de la consulta:

* Las preguntas del producto: `<id>:<engine>:<ask>`, como `eye-bomb-us:CHATGPT:buy`. Las preguntas de ChatGPT son `buy` y `price`, y la de los demás motores es `name`.
* Las preguntas del enésimo competidor añaden `:c<n>`, como `eye-bomb-us:CHATGPT:buy:c1`.
* Las preguntas del enésimo prompt: `<id>:<engine>:p<n>`, como `eye-bomb-us:AIMODE:p1`.

Si vuelves a enviar una consulta con el mismo `idempotencyKey`, la API devuelve las preguntas que ya existen y añade solo las que faltan, y solo se te cobran las que añade. Úsalo para terminar una consulta cuyas preguntas se rechazaron por falta de créditos o por concurrencia, o para añadir un competidor o un prompt al final de su lista. Un competidor o un prompt que omitas sigue en la consulta.

Un reenvío que cambia el producto o el país, o que pone un competidor o un prompt distinto en una posición que ya tiene uno, devuelve `409 RESOURCE_ALREADY_EXISTS` y no escribe nada. Un reenvío devuelve tal cual una pregunta que falló. Para que los motores respondan de nuevo, envía la consulta con un `idempotencyKey` nuevo.

## Precio

Una consulta cuesta 10 créditos por producto, el producto y cada competidor, y 5 créditos por prompt de compra, sean cuales sean los motores a los que preguntes.

* La consulta de arriba cuesta 3 × 10 + 2 × 5 = 40 créditos. La consulta más grande, un producto con 5 competidores y 3 prompts, cuesta 75 créditos.
* Los créditos de un producto o de un prompt se reparten entre sus preguntas. Con los motores por defecto de `US`, una pregunta de producto cuesta 2 créditos y una de prompt 1,25. Con los de `KR`, una pregunta de producto cuesta 2,5 créditos y las tres preguntas de un prompt cuestan 1,67, 1,67 y 1,66. Preguntar a menos motores no baja el precio: solo con ChatGPT, cada una de las dos preguntas de un producto cuesta 5 créditos.
* Cada pregunta se retiene al enviarla y se cobra cuando se completa, como cualquier tarea. Una pregunta que falla no se cobra.
* A precio de plan, un producto cuesta \$0,025 en Basic y \$0,010 en Max.

Consulta [Créditos y límites](/es/concepts/credits-and-limits.md) para las retenciones y los planes.

## Cómo leer bien los resultados

* **Una consulta es una instantánea.** Cada motor responde a una o dos preguntas. Antes de actuar por una sola diferencia, vuelve a lanzar la consulta con un `idempotencyKey` nuevo.
* **Los registros mantienen sus valores; lo que cambia es la selección.** En cuatro ejecuciones de una misma consulta, el mismo registro de un comercio mantuvo su precio, su valoración y su número de reseñas en 307 de 316 valores. Lo que cambia de una ejecución a otra es qué registros muestra una respuesta, así que `found` (sobre todo en ChatGPT), los comercios, `mostReviewed`, `priceRange` y los `shown` y `named` de los prompts pueden variar.
* **Unos minutos de diferencia cambian tanto como unas horas.** Las respuestas de ChatGPT, AI Mode y Copilot variaron lo mismo con tres minutos de diferencia que con once horas. AI Overviews puede devolver la misma respuesta si se le pregunta de nuevo a los pocos segundos, así que repetir enseguida no da una muestra nueva.
* **Los totales son más estables que las respuestas sueltas.** En las cuatro ejecuciones, las respuestas a los prompts de compra cambiaron una a una, pero los productos que aparecieron en más respuestas encabezaron todas las ejecuciones. Para seguir prompts a lo largo del tiempo, usa un [monitor GEO](/es/monitors.md).
* **`found: false` describe estas respuestas.** Significa que las preguntas de esta ejecución no mostraron el producto. No significa que el catálogo del motor no lo tenga.
* **La coincidencia se basa en nombres.** Ningún motor devuelve un GTIN. Un producto con otro nombre o traducido puede acabar en `otherListings`, y una versión que su nombre no distingue puede contar como el producto. Revisa `match` cuando una oferta no encaje.

## Límites

* La entrada es el nombre de un producto. No se admiten URLs de páginas de producto ni GTIN.
* Los mercados son `US` y `KR`.
* Una consulta admite hasta 5 competidores y 3 prompts de compra. Con los motores por defecto de `US`, la consulta más grande hace 42 preguntas.
* Los competidores son los que tú indicas. Una consulta no los busca por ti; los prompts de compra muestran qué productos pone un motor delante de los compradores.
* Se leen los registros y las tarjetas de widget de ChatGPT, pero no las tiendas ni los precios que escribe en el texto o en las tablas de la respuesta.
* Cada respuesta aporta como máximo 60 ofertas y 20 páginas citadas.
* Una consulta se puede leer mientras se puedan leer las tareas de sus preguntas, hasta 24 horas después de que se completen. Consulta [Tareas asíncronas](/es/concepts/async-tasks.md#retención).

## Errores

### Rechazos al enviar

| Estado | Código | Causa |
| - | - | - |
| `400` | `VALIDATION_ERROR` | El cuerpo no es JSON válido, o un campo incumple una de las reglas de arriba: falta `product` o `country`, el nombre es una URL o un GTIN, hay demasiados `competitors` o `prompts` o están repetidos, un motor es desconocido o no se ofrece en el mercado, o el `idempotencyKey` no es válido. `details` indica el campo. |
| `422` | `REGION_UNSUPPORTED` | `country` no es `US` ni `KR`. |
| `409` | `RESOURCE_ALREADY_EXISTS` | El `idempotencyKey` nombra una consulta de otro producto o de otro país, o una con un competidor o un prompt distinto en la misma posición. No se escribió nada. |

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "product",
        "message": "product takes a product's name; a GTIN or barcode is not supported"
      }
    ],
    "timestamp": "2026-10-20T09:00:00.000Z"
  }
}
```

### Preguntas rechazadas

Cada pregunta se admite como una tarea individual, así que puede rechazarse por tu saldo (`402 INSUFFICIENT_CREDITS`), por la concurrencia de tu plan (`429 PLAN_CONCURRENCY_LIMIT`), por el límite diario de créditos de una clave (`429 KEY_DAILY_CREDIT_LIMIT`) o por una clave limitada a otros motores. Una pregunta rechazada queda en `asks[]` con `success: false` y su `error`, y las demás preguntas siguen adelante.

Las preguntas se admiten de una en una: la primera pregunta de cada motor sobre cada producto, y cada prompt, van antes que cualquier segunda pregunta. Así, cuando tu plan solo tiene sitio para algunas preguntas, las admitidas cubren tantos motores y productos como pueden. Si no se admite ninguna de las primeras preguntas del producto, no se pregunta nada más, y la respuesta de la API es el primer rechazo con su estado, como `402 INSUFFICIENT_CREDITS`. Con las 2 tareas simultáneas del plan Free, una consulta en `US` admite las primeras preguntas del producto a ChatGPT y a AI Overviews; vuelve a enviarla cuando terminen para añadir el resto. La consulta más grande en `US`, de 42 preguntas, cabe en las 50 tareas simultáneas de Basic cuando no hay nada más en cola.

Los errores de autenticación son los mismos que en cualquier solicitud. Consulta [Errores](/es/concepts/errors.md).

### Preguntas fallidas y lecturas

* Una pregunta que falla tiene `status: "FAILED"` y un `error` en `via[]`, y no se cobra. Un motor en el que fallaron todas las preguntas tiene `status: "FAILED"` y `found: null`, y aparece en `summary.failed`.
* `GET /v1/product-lookup/{id}` devuelve `404 RESOURCE_NOT_FOUND` para un id sin consulta en tu cuenta, incluida una consulta cuyas tareas ya pasaron el plazo de lectura.

## Próximos pasos

> **[Monitores GEO](/es/monitors.md)**
>
> Sigue prompts de compra en los motores de IA de forma programada.

> **[Prompt Research](/es/research/prompt-research.md)**
>
> Encuentra las preguntas de compra que la gente hace sobre una categoría.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.