> ## 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: veja como os mecanismos de compra com IA mostram um produto

> Pergunte ao ChatGPT, ao Google AI Overviews, ao AI Mode, ao Copilot e ao Naver AI Tab sobre um produto e veja, mecanismo por mecanismo, se a resposta o mostrou, quais ofertas de lojas usou e quais páginas citou.

Use o Product Lookup para ver um produto do jeito que os mecanismos de compra com IA o mostram aos compradores. Envie o nome de um produto e um mercado, e o querying.ai pergunta sobre ele a cada mecanismo. Para cada mecanismo, você fica sabendo se a resposta mostrou o produto, quais ofertas de lojas ela exibiu (loja, catálogo, preço, estoque, nota e número de avaliações) e quais páginas ela cita. Adicione até cinco concorrentes para compará-los mecanismo por mecanismo, e até três prompts de compra, como `best moisturizing eye cream`, para ver quais desses produtos cada mecanismo mostra a um comprador.

Uma consulta mostra, por exemplo:

* se o ChatGPT, o Google AI Overviews, o AI Mode ou o Copilot mostram o produto quando perguntados sobre ele;
* de quais lojas e registros de catálogo cada mecanismo o mostra, a que preço, com que nota e quantas avaliações;
* o que o modelo que responde no ChatGPT leu sobre o produto;
* como o produto se sai diante dos concorrentes em cada mecanismo;
* quais desses produtos cada mecanismo mostra para uma busca de compra.

## Envie uma 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"
  }'
```

A consulta é dividida em perguntas: cada pergunta vai a um mecanismo, sobre um produto ou um prompt. Cada pergunta entra na fila como uma tarefa comum, e a resposta da API as lista. Aqui ela foi reduzida a três das 23 perguntas:

```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` é o seu `idempotencyKey`, ou um UUID escolhido pelo servidor quando você não envia nenhum. É com ele que você lê a consulta.
* Cada entrada de `asks[]` tem seu `role` (`product`, `competitor` ou `prompt`), o texto perguntado em `prompt` ou `query`, e sua `task`. Uma pergunta recusada tem `success: false` e um `error` no lugar de `task`. Veja [Erros](#erros).
* `credits.creditsToCharge` soma os preços das perguntas retornadas, que ficam reservados no seu saldo até cada pergunta terminar. `creditsCharged` é o que já foi cobrado delas.

Leia a consulta com `GET /v1/product-lookup/{id}` até `lookup.status` ser `COMPLETED`. Esta consulta levou cerca de dois minutos; uma consulta termina quando o mecanismo mais lento responde. Com `webhook.url`, a tarefa de cada pergunta é enviada a você quando termina, com a chave da pergunta em `task.idempotencyKey`, que começa com o id da consulta. Nenhum webhook cobre a consulta inteira, então leia a consulta a cada entrega e confira `lookup.status`. Os schemas estão na referência da API: [Product Lookup](/pt/api-reference/product-lookup.md) e [Obter um Product Lookup](/pt/api-reference/get-product-lookup.md).

## Campos da requisição

| Campo | Obrigatório | Descrição |
| - | - | - |
| `product` | Sim | O nome do produto como os compradores o escrevem, de 1 a 200 caracteres, como `belif Moisturizing Eye Bomb`. Uma URL de página de produto ou um GTIN retorna `400 VALIDATION_ERROR`. |
| `country` | Sim | `US` (Estados Unidos) ou `KR` (Coreia do Sul), sem diferenciar maiúsculas de minúsculas. Qualquer outro valor retorna `422 REGION_UNSUPPORTED`. |
| `competitors` | Não | Até 5 nomes de outros produtos, com as regras de `product`. Cada um recebe as mesmas perguntas do produto. Um nome igual ao do produto, ou repetido, retorna `400`. Nomes que só diferem em maiúsculas, pontuação ou espaços contam como iguais. |
| `prompts` | Não | Até 3 prompts de compra de 1 a 300 caracteres, como `best moisturizing eye cream`. Cada um é perguntado uma vez a cada mecanismo, exatamente como foi escrito. |
| `engines` | Não | Os mecanismos a consultar: `CHATGPT`, `GOOGLE`, `AIMODE`, `BING_COPILOT`, `GEMINI`, e `NAVER_AI_TAB` só em `KR`. O padrão são os mecanismos do mercado indicados abaixo. |
| `idempotencyKey` | Não | Dá nome à consulta: de 1 a 200 caracteres, sem espaços no início ou no fim. Veja [Reenvie uma consulta](#reenvie-uma-consulta). |
| `priority` | Não | Inteiro de `1` a `10`, padrão `1`, aplicado a cada pergunta. Valores fora do intervalo são ajustados ao limite mais próximo. Não garante a ordem de execução. |
| `webhook.url` | Não | Recebe a tarefa de cada pergunta quando ela termina. Veja [Webhooks](/pt/concepts/webhooks.md). |

## Mecanismos e perguntas

O produto e cada concorrente recebem as mesmas perguntas:

| Mecanismo | `US` | `KR` |
| - | - | - |
| `CHATGPT` | `Buy {product}` e `Find the best price for {product}` | `{product} 구매` e `{product} 최저가` |
| `GOOGLE` (AI Overviews) | O nome do produto | O nome do produto, sob demanda |
| `AIMODE` (AI Mode) | O nome do produto | O nome do produto |
| `BING_COPILOT` (Copilot) | O nome do produto | O nome do produto, sob demanda |
| `NAVER_AI_TAB` (Naver AI Tab) | Indisponível | O nome do produto |
| `GEMINI` | O nome do produto, sob demanda | O nome do produto, sob demanda |

"Sob demanda" significa que o mecanismo só é consultado quando você o inclui em `engines`. Sem `engines`, uma consulta `US` pergunta ao ChatGPT, ao AI Overviews, ao AI Mode e ao Copilot, ou seja, 5 perguntas por produto. Uma consulta `KR` pergunta ao Naver AI Tab, ao ChatGPT e ao AI Mode, 4 perguntas por produto. Um prompt de compra é perguntado uma vez a cada mecanismo: 4 perguntas com os mecanismos padrão de `US` e 3 com os de `KR`. A consulta acima fez 3 × 5 + 2 × 4 = 23 perguntas.

O ChatGPT recebe duas perguntas porque uma só mostra um registro do produto para cerca de metade dos produtos, e a mesma pergunta repetida costuma acertar outra metade. Os outros mecanismos padrão são os que mostraram produtos em um teste com 50 produtos em 2026-10-20:

| Mecanismo | `US` | `KR` |
| - | - | - |
| ChatGPT, as duas perguntas, com cartões 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 |

A linha do ChatGPT vem de 12 produtos `US` e 10 `KR`, consultados duas vezes cada. O Gemini não mostrou nenhum registro de produto em 115 perguntas nos dois mercados.

## Leia a consulta

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

O resultado tem cinco partes:

* `lookup`: o que foi perguntado, seu `status` e os `credits` cobrados até agora.
* `summary` e `engines[]`: as respostas sobre o produto, no conjunto dos mecanismos e mecanismo por mecanismo.
* `competitors[]`: os mesmos `summary` e `engines[]` para cada concorrente.
* `comparison[]`: o produto e os concorrentes lado a lado, mecanismo por mecanismo.
* `prompts[]`: o que cada mecanismo respondeu a cada prompt de compra.

`lookup.status` é `QUEUED` até alguma pergunta começar e `PROCESSING` enquanto houver pergunta não terminada. Passa a `COMPLETED` quando todas as perguntas terminaram e pelo menos uma foi concluída, e a `FAILED` quando todas falharam. As entradas são preenchidas conforme as perguntas terminam, então você pode ler uma consulta antes de ela ser concluída.

Aqui estão `lookup`, `summary` e `engines[]` da consulta acima, reduzidos a dois dos quatro mecanismos e a poucas 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
        }
      ]
    }
  ]
}
```

Os quatro mecanismos mostraram o produto. O ChatGPT mostrou um registro do feed de produtos da Ulta Beauty, e o modelo que responde leu nele nota 4,5 com 105 avaliações. O ChatGPT também escreveu cartões de widget para três lojas, entre elas a Amazon. O AI Mode mostrou a oferta de uma loja e uma versão em bastão marcada como `variant`, e colocou o gel para a área dos olhos da marca em `otherListings`.

### `summary`

| Campo | Descrição |
| - | - |
| `foundIn`, `notFoundIn` | Os mecanismos cujas respostas mostraram o produto, e os mecanismos cujas perguntas terminaram sem mostrá-lo. |
| `pending`, `failed` | Os mecanismos com perguntas ainda em andamento, e os mecanismos em que todas as perguntas falharam. |
| `merchants[]` | Cada loja das ofertas do produto, com os `engines` que a mostraram e sua faixa de `price` unitário neles; primeiro, as que aparecem em mais mecanismos. |
| `priceRange` | Preços unitários em todos os mecanismos, na moeda do mercado: USD para `US` e KRW para `KR`. Ofertas de outra embalagem ou formato (`match.variant`) ficam de fora. |
| `citedDomains[]` | Cada site citado pelas respostas, com os `engines` que o citam; primeiro, os citados por mais mecanismos. |
| `credits` | Créditos cobrados até agora pelas perguntas do produto. `lookup.credits` cobre a consulta inteira. |

### `engines[]`

Uma entrada por mecanismo consultado:

| Campo | Descrição |
| - | - |
| `status` | As perguntas do mecanismo em conjunto: `QUEUED`, `PROCESSING`, `COMPLETED` quando todas terminaram e uma foi concluída, ou `FAILED` quando todas falharam. |
| `found` | `true` quando uma resposta mostrou uma oferta do produto, vinda de um registro de catálogo ou de um cartão de widget do ChatGPT. `false` quando todas as perguntas terminaram sem nenhuma. `null` enquanto há perguntas em andamento e nada foi encontrado ainda, e quando todas as perguntas falharam. |
| `via[]` | As perguntas do mecanismo em ordem, cada uma com o texto perguntado, seu `taskId`, `status` e `credits`, e o `error` de uma pergunta que falhou. |
| `listings[]` | Ofertas consideradas o produto, ou outra embalagem ou formato dele. Uma oferta mostrada por duas perguntas aparece uma vez só. |
| `otherListings[]` | Outros produtos que as respostas mostraram. Uma versão do produto com outro nome ou traduzida pode aparecer aqui. |
| `citedPages[]` | As páginas citadas pelas respostas, cada uma com `url`, `domain` (o host sem `www.` ou `m.`), `title` e `ask`. No ChatGPT, são as fontes que a resposta dele cita. |

### Campos de uma oferta

Uma oferta é o registro do produto de uma loja, tal como o mecanismo o guarda. Ela traz só os campos que o mecanismo fornece.

| Campo | Descrição |
| - | - |
| `position` | Ordem na resposta, a partir de 1. |
| `ask` | Qual pergunta do mecanismo a mostrou, a partir de 1, na ordem de `via[]`. |
| `title` | O nome do produto no registro. Em um cartão de widget do ChatGPT, o título do cartão, que pode ser o nome da loja. |
| `merchant` | Quem vende. |
| `source` | De onde vem a oferta. Veja a próxima tabela. |
| `url` | A página da loja quando o mecanismo tem um link para ela; caso contrário, a página de produto do próprio mecanismo. |
| `price`, `oldPrice` | `value`, `currency` e `raw` como exibido. `currency` é um código ISO 4217 quando o símbolo não é ambíguo no mercado. `oldPrice` é o preço antes de um desconto que o mecanismo mostra. |
| `available` | Se há estoque. Só no ChatGPT. |
| `rating`, `reviewCount` | A nota e o número de avaliações do registro. |
| `modelSees` | Só no ChatGPT: o que o ChatGPT passou ao modelo que responde sobre o registro: `title`, `description`, `rating`, `reviewCount`, `brand` e `productPage`. A nota e o número de avaliações de um registro vindo do feed de uma loja só aparecem aqui. |
| `image`, `description`, `brand` | Como o mecanismo os mostra. |
| `reviews` | O `summary`, os `pros` e os `cons` das avaliações que o mecanismo mostra. |
| `ids` | Identificadores de catálogo que ligam os registros de um mesmo produto, como `chatgptProductId` e `feedId` no ChatGPT, `googleCatalogId`, `googleProductGroupId` e `googleProductDocId` nos mecanismos do Google, `bingProductId` e `bingGroupId` no Copilot, e `naverProductId` no Naver AI Tab. Nenhum mecanismo retorna GTIN. |
| `pictured` | Em um cartão de widget do ChatGPT: o que a imagem ao lado do cartão mostra, segundo a busca que a resposta escreveu para encontrá-la. |
| `match` | Por que a oferta conta como o produto. `score` é a fração das palavras do nome do produto encontradas na oferta, de 0 a 1. `missing` lista as palavras não encontradas, `variant` marca outra embalagem ou formato (kit, mini, 1+1, bastão) e `accessory` uma peça em vez do produto, como um filtro de reposição. |

`source` indica de qual catálogo vem uma oferta:

| `source` | Mecanismo | O que é |
| - | - | - |
| `shopify` | ChatGPT | O registro de uma loja Shopify no catálogo de produtos do ChatGPT |
| `merchant_feed` | ChatGPT | Um registro do feed de produtos que uma loja envia ao ChatGPT |
| `google_shopping` | ChatGPT, AI Overviews, AI Mode, Gemini | Um registro do Google Shopping |
| `chatgpt_catalog` | ChatGPT | Um registro do catálogo do ChatGPT que não informa a origem |
| `chatgpt_widget` | ChatGPT | Uma loja e um preço que o ChatGPT escreveu em um cartão de widget, sem registro por trás |
| `microsoft_shopping` | Copilot | Uma oferta do Microsoft Shopping |
| `naver_shopping` | Naver AI Tab | Uma oferta do Naver Shopping |

### Cartões de widget do ChatGPT

O ChatGPT costuma responder a uma busca de compra com cartões que indicam, cada um, uma loja e um preço que ele leu na página da loja, sem registro de catálogo por trás. O Product Lookup lê cada cartão como uma oferta `chatgpt_widget`, depois dos registros da resposta, e o conta para `found`.

* `merchant` é a loja que o cartão indica, ou o domínio do link de compra. `description` é a linha de descrição do cartão.
* Um cartão não tem `rating`, `reviewCount`, `available`, `ids` nem `modelSees`. Com uma faixa de preço como `$40–$62`, `price` fica de fora.
* Um cartão sem link de compra e sem linha de vendedor não é lido.
* Um cartão com a mesma loja e o mesmo preço de um registro ou de um cartão anterior do produto é descartado. Duas lojas são a mesma quando os nomes ou os sites vinculados coincidem, ou quando um começa com o outro, como Ulta, Ulta Beauty e ulta.com.

Para ler só registros de catálogo, deixe de fora as ofertas cujo `source` é `chatgpt_widget`.

## Compare com os concorrentes

Uma pergunta sobre um produto raramente mostra o produto de outra marca; no teste com 50 produtos, isso não aconteceu nenhuma vez. Por isso é você quem indica os concorrentes, e cada um recebe as perguntas do produto. Cada entrada de `competitors[]` tem o `product`, o `summary` e os `engines[]` do concorrente, que se leem como os do produto.

`comparison[]` alinha o produto e os concorrentes, com uma linha por produto e uma entrada por mecanismo. Da consulta acima, reduzida ao Copilot, com o ChatGPT a mais para o produto:

```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 | Descrição |
| - | - |
| `role` | `product` ou `competitor`. |
| `found` | Como em `engines[]`. |
| `listings` | Quantas ofertas são consideradas o produto, contando os cartões de widget do ChatGPT. |
| `merchants` | Quantas lojas há entre essas ofertas. |
| `mostReviewed` | A oferta com mais avaliações: seu `reviewCount`, `rating` e `merchant`. No ChatGPT, o número que o modelo que responde recebeu em `modelSees`. O Copilot põe o número de avaliações de um produto na oferta de cada loja, então `merchant` é a primeira oferta que o traz. |
| `priceRange` | Preços unitários nesse mecanismo. |
| `prompts` | Só quando a consulta tem prompts de compra: `answered` é quantos deles o mecanismo respondeu, e `appeared`, em quantas dessas respostas o produto foi mostrado ou mencionado. |

Os três produtos foram encontrados nos quatro mecanismos. No Copilot, a oferta do produto com mais avaliações tem 2.942, contra 85.773 e 117.193 dos dois concorrentes. Nas oito respostas a prompts de compra, o CeraVe Eye Repair Cream apareceu em cinco, e o produto e o Clinique All About Eyes em duas cada.

## Prompts de compra

Cada entrada de `prompts[]` tem o `prompt` e uma entrada por mecanismo em `engines[]`:

| Campo | Descrição |
| - | - |
| `shown` | Os produtos da consulta, o produto e os concorrentes, que a resposta mostrou como registro ou cartão de widget, na ordem em que aparecem. |
| `named` | Os produtos da consulta que o texto da resposta menciona, na ordem em que são mencionados. |
| `listings[]` | Cada registro de produto e cada cartão de widget da resposta. Os que são um produto da consulta trazem `product` e `match`. |
| `via[]`, `citedPages[]` | Como em `engines[]`. |

A resposta a um prompt de compra mostra produtos de muitas marcas, então um registro só conta como um dos produtos da consulta quando contém a marca, isto é, a primeira palavra do nome do produto. Um nome no texto conta do mesmo jeito que um [monitor GEO](/pt/monitors.md) conta uma menção de marca, com o nome completo do produto como termo.

Da consulta acima, as respostas do AI Overviews e do Copilot a `best moisturizing eye cream`, com as ofertas reduzidas aos produtos da 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"
            }
          ]
        }
      ]
    }
  ]
}
```

O AI Overviews mencionou o produto no texto, mas só mostrou registros dos dois concorrentes. O Copilot mostrou o produto em três lojas. A correspondência usa os nomes, então uma versão cujo nome acrescenta uma palavra, como `Clinique All About Eyes Rich`, conta como o produto correspondente.

## Reenvie uma consulta

Cada pergunta tem sua própria chave, formada a partir do id da consulta:

* As perguntas do produto: `<id>:<engine>:<ask>`, como `eye-bomb-us:CHATGPT:buy`. As perguntas do ChatGPT são `buy` e `price`, e a dos outros mecanismos é `name`.
* As perguntas do n-ésimo concorrente acrescentam `:c<n>`, como `eye-bomb-us:CHATGPT:buy:c1`.
* As perguntas do n-ésimo prompt: `<id>:<engine>:p<n>`, como `eye-bomb-us:AIMODE:p1`.

Quando você reenvia uma consulta com o mesmo `idempotencyKey`, a API retorna as perguntas que já existem e acrescenta só as que faltam, e você só paga pelas perguntas acrescentadas. Use isso para concluir uma consulta cujas perguntas foram recusadas por falta de créditos ou pelo limite de concorrência, ou para acrescentar um concorrente ou um prompt no fim da lista. Um concorrente ou prompt que você omitir continua na consulta.

Um reenvio que muda o produto ou o país, ou que põe outro concorrente ou outro prompt em uma posição já ocupada, retorna `409 RESOURCE_ALREADY_EXISTS` e não grava nada. Uma pergunta que falhou volta como está no reenvio. Para obter novas respostas dos mecanismos, envie a consulta com um `idempotencyKey` novo.

## Preço

Uma consulta custa 10 créditos por produto, o produto e cada concorrente, e 5 créditos por prompt de compra, quaisquer que sejam os mecanismos consultados.

* A consulta acima custa 3 × 10 + 2 × 5 = 40 créditos. A maior consulta, um produto com 5 concorrentes e 3 prompts, custa 75 créditos.
* Os créditos de um produto ou de um prompt são divididos entre suas perguntas. Com os mecanismos padrão de `US`, uma pergunta de produto custa 2 créditos e uma de prompt, 1,25. Com os de `KR`, uma pergunta de produto custa 2,5 créditos e as três perguntas de um prompt custam 1,67, 1,67 e 1,66. Consultar menos mecanismos não reduz o preço: só com o ChatGPT, cada uma das duas perguntas de um produto custa 5 créditos.
* Cada pergunta é reservada no envio e cobrada quando é concluída, como qualquer tarefa. Uma pergunta que falha não é cobrada.
* Pelos preços dos planos, um produto custa \$0,025 no Basic e \$0,010 no Max.

Veja [Créditos e limites](/pt/concepts/credits-and-limits.md) para reservas e planos.

## Como ler os resultados corretamente

* **Uma consulta é um retrato do momento.** Cada mecanismo responde a uma ou duas perguntas. Antes de agir por causa de uma única diferença, rode a consulta de novo com um `idempotencyKey` novo.
* **Os registros mantêm os valores; o que muda é a seleção.** Em quatro execuções de uma mesma consulta, o mesmo registro de loja manteve preço, nota e número de avaliações em 307 de 316 valores. O que muda de uma execução para outra é quais registros uma resposta mostra, então `found` (com mais frequência no ChatGPT), as lojas, `mostReviewed`, `priceRange` e os `shown` e `named` dos prompts podem variar.
* **Minutos de intervalo mudam tanto quanto horas.** As respostas do ChatGPT, do AI Mode e do Copilot variaram tanto com três minutos de intervalo quanto com onze horas. O AI Overviews, perguntado de novo em poucos segundos, pode devolver a mesma resposta, então uma repetição rápida ali não é uma amostra nova.
* **Totais são mais estáveis que respostas isoladas.** Nas quatro execuções, as respostas aos prompts de compra mudaram uma a uma, mas os produtos que apareceram em mais respostas lideraram em todas as execuções. Para acompanhar prompts ao longo do tempo, use um [monitor GEO](/pt/monitors.md).
* **`found: false` descreve estas respostas.** Significa que as perguntas desta execução não mostraram o produto. Não significa que o catálogo do mecanismo não o tenha.
* **A correspondência usa os nomes.** Nenhum mecanismo retorna GTIN. Um produto renomeado ou traduzido pode cair em `otherListings`, e uma versão que o nome não distingue pode contar como o produto. Confira `match` quando uma oferta parecer errada.

## Limites

* A entrada é o nome de um produto. URLs de páginas de produto e GTINs não são aceitos.
* Os mercados são `US` e `KR`.
* Uma consulta aceita até 5 concorrentes e 3 prompts de compra. Com os mecanismos padrão de `US`, a maior consulta faz 42 perguntas.
* Os concorrentes são os que você indica. A consulta não os encontra por você; os prompts de compra mostram quais produtos um mecanismo põe diante dos compradores.
* São lidos os registros e os cartões de widget do ChatGPT. As lojas e os preços que ele escreve no texto ou nas tabelas da resposta não são lidos.
* Cada resposta contribui com no máximo 60 ofertas e 20 páginas citadas.
* Uma consulta pode ser lida enquanto as tarefas das suas perguntas puderem ser lidas, até 24 horas depois de concluídas. Veja [Tarefas assíncronas](/pt/concepts/async-tasks.md#retenção).

## Erros

### Rejeições no envio

| Status | Código | Causa |
| - | - | - |
| `400` | `VALIDATION_ERROR` | O corpo não é JSON válido, ou um campo viola uma regra acima: falta `product` ou `country`, um nome é URL ou GTIN, há `competitors` ou `prompts` demais ou repetidos, um mecanismo é desconhecido ou não é oferecido no mercado, ou o `idempotencyKey` é inválido. `details` indica o campo. |
| `422` | `REGION_UNSUPPORTED` | `country` não é `US` nem `KR`. |
| `409` | `RESOURCE_ALREADY_EXISTS` | O `idempotencyKey` nomeia uma consulta de outro produto ou país, ou uma com outro concorrente ou prompt na mesma posição. Nada foi gravado. |

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

### Perguntas recusadas

Cada pergunta é admitida como uma tarefa avulsa, então pode ser recusada pelo seu saldo (`402 INSUFFICIENT_CREDITS`), pela concorrência do seu plano (`429 PLAN_CONCURRENCY_LIMIT`), pelo limite diário de créditos de uma chave (`429 KEY_DAILY_CREDIT_LIMIT`) ou por uma chave restrita a outros mecanismos. Uma pergunta recusada fica em `asks[]` com `success: false` e seu `error`, e as demais perguntas seguem.

As perguntas são admitidas uma de cada vez: a primeira pergunta de cada mecanismo sobre cada produto, e cada prompt, vêm antes de qualquer segunda pergunta. Assim, quando o seu plano só tem espaço para parte das perguntas, as admitidas cobrem o máximo possível de mecanismos e produtos. Se nenhuma das primeiras perguntas do produto for admitida, nada mais é perguntado, e a resposta da API é a primeira recusa com seu status, como `402 INSUFFICIENT_CREDITS`. Com as 2 tarefas simultâneas do plano Free, uma consulta `US` admite as primeiras perguntas do produto ao ChatGPT e ao AI Overviews; reenvie a consulta quando elas terminarem para acrescentar o restante. A maior consulta `US`, com 42 perguntas, cabe nas 50 tarefas simultâneas do Basic quando não há mais nada na fila.

Os erros de autenticação são os mesmos de qualquer requisição. Veja [Erros](/pt/concepts/errors.md).

### Perguntas com falha e leituras

* Uma pergunta que falha tem `status: "FAILED"` e um `error` em `via[]`, e não é cobrada. Um mecanismo em que todas as perguntas falharam tem `status: "FAILED"` e `found: null`, e aparece em `summary.failed`.
* `GET /v1/product-lookup/{id}` retorna `404 RESOURCE_NOT_FOUND` para um id sem consulta na sua conta, inclusive uma consulta cujas tarefas já passaram do prazo de leitura.

## Próximos passos

> **[Monitores GEO](/pt/monitors.md)**
>
> Acompanhe prompts de compra nos mecanismos de IA de forma agendada.

> **[Prompt Research](/pt/research/prompt-research.md)**
>
> Encontre as perguntas de compra que as pessoas fazem sobre uma categoria.


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