> ## 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: see how AI shopping engines show a product

> Ask ChatGPT, Google AI Overviews, AI Mode, Copilot and Naver AI Tab about a product and see, per engine, whether the answer showed it, the merchant listings it used and the pages it cited.

Use Product Lookup to see a product the way AI shopping engines show it to shoppers. Send a product name and a
market, and querying.ai asks each engine about it. For every engine you get whether the answer showed the product,
the merchant listings it showed (merchant, catalog, price, stock, rating and review count) and the pages it cites.
Add up to five competitors to compare them engine by engine, and up to three shopper prompts, such as
`best moisturizing eye cream`, to see which of these products each engine shows a shopper.

A lookup answers questions like these:

* Does ChatGPT, Google AI Overviews, AI Mode or Copilot show the product when asked about it?
* Which merchants and catalog records does each engine show it from, at what price, with what rating and review count?
* What did ChatGPT's answering model read about the product?
* How does the product compare with its competitors on each engine?
* Which of these products does each engine show for a shopping question?

## Submit a lookup

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

The lookup is split into asks: one question to one engine about one product or prompt. Each ask is queued as an
ordinary task, and the response lists them. Here it is trimmed to three of the 23 asks:

```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` is your `idempotencyKey`, or a UUID the server picks when you send none. You read the lookup with it.
* Each entry of `asks[]` has its `role` (`product`, `competitor` or `prompt`), the text asked in `prompt` or
  `query`, and its `task`. A refused ask has `success: false` and an `error` instead. See [Errors](#errors).
* `credits.creditsToCharge` adds up the prices of the asks in the response, held from your balance until each ask
  finishes. `creditsCharged` is what they were charged already.

Read the lookup with `GET /v1/product-lookup/{id}` until `lookup.status` is `COMPLETED`. This lookup took about
two minutes; a lookup ends when its slowest engine answers. With `webhook.url`, each ask's task is posted to you
when it finishes, with the ask's key in `task.idempotencyKey`, which starts with the lookup id. No webhook covers
the whole lookup, so read the lookup on each delivery and check `lookup.status`. The schemas are in the API
reference: [Product Lookup](/api-reference/product-lookup.md) and [Get a product lookup](/api-reference/get-product-lookup.md).

## Request fields

| Field | Required | Description |
| - | - | - |
| `product` | Yes | The product's name as shoppers write it, 1–200 characters, such as `belif Moisturizing Eye Bomb`. A product page URL or a GTIN returns `400 VALIDATION_ERROR`. |
| `country` | Yes | `US` (United States) or `KR` (South Korea), case-insensitive. Any other value returns `422 REGION_UNSUPPORTED`. |
| `competitors` | No | Up to 5 other products' names, with the rules of `product`. Each is asked what the product is asked. A name that is the product's, or one listed twice, returns `400`. Names that differ only in case, punctuation or spacing count as the same. |
| `prompts` | No | Up to 3 shopper prompts of 1–300 characters, such as `best moisturizing eye cream`. Each is asked of each engine once, as written. |
| `engines` | No | The engines to ask: `CHATGPT`, `GOOGLE`, `AIMODE`, `BING_COPILOT`, `GEMINI`, and `NAVER_AI_TAB` in `KR` only. Defaults to the market's engines below. |
| `idempotencyKey` | No | Names the lookup: 1–200 characters without leading or trailing spaces. See [Send a lookup again](#send-a-lookup-again). |
| `priority` | No | Integer `1`–`10`, default `1`, set on every ask. Out-of-range values are clamped. It does not guarantee execution order. |
| `webhook.url` | No | Receives each ask's task when it finishes. See [Webhooks](/concepts/webhooks.md). |

## Engines and asks

The product and each competitor get the same asks:

| Engine | `US` | `KR` |
| - | - | - |
| `CHATGPT` | `Buy {product}` and `Find the best price for {product}` | `{product} 구매` and `{product} 최저가` |
| `GOOGLE` (AI Overviews) | The product name | The product name, on request |
| `AIMODE` (AI Mode) | The product name | The product name |
| `BING_COPILOT` (Copilot) | The product name | The product name, on request |
| `NAVER_AI_TAB` (Naver AI Tab) | Not available | The product name |
| `GEMINI` | The product name, on request | The product name, on request |

"On request" means the engine is asked only when you list it in `engines`. Without `engines`, a `US` lookup asks
ChatGPT, AI Overviews, AI Mode and Copilot, which is 5 asks per product. A `KR` lookup asks Naver AI Tab, ChatGPT
and AI Mode, which is 4 asks per product. A shopper prompt is asked once of each engine: 4 asks on the `US`
defaults and 3 on the `KR` defaults. The lookup above made 3 × 5 + 2 × 4 = 23 asks.

ChatGPT gets two asks because one ask shows a product record for about half of the products, and the same ask
repeated often finds a different half. The other defaults are the engines that showed products in a test of 50
products on 2026-10-20:

| Engine | `US` | `KR` |
| - | - | - |
| ChatGPT, both asks, widget cards included | 24 of 24 lookups | 20 of 20 lookups |
| Copilot | 25 of 25 | 0 of 25 |
| Google AI Overviews | 23 of 25 | 1 of 25 |
| Google AI Mode | 23 of 25 | 13 of 25 |
| Naver AI Tab | – | 25 of 25 |

The ChatGPT row comes from 12 `US` and 10 `KR` products looked up twice each. Gemini showed no product record in
115 asks across both markets.

## Read the lookup

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

The result has five parts:

* `lookup`: what was asked, its `status` and the `credits` charged so far.
* `summary` and `engines[]`: the product's answers, across engines and engine by engine.
* `competitors[]`: the same `summary` and `engines[]` for each competitor.
* `comparison[]`: the product and its competitors side by side, engine by engine.
* `prompts[]`: what each engine answered to each shopper prompt.

`lookup.status` is `QUEUED` until an ask starts and `PROCESSING` while any ask is unfinished. It becomes
`COMPLETED` once every ask has finished and at least one completed, and `FAILED` when all of them failed. Entries
fill in as asks finish, so you can read a lookup before it completes.

Here are the `lookup`, `summary` and `engines[]` of the lookup above, trimmed to two of the four engines and a few
entries per list:

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

All four engines showed the product. ChatGPT showed a merchant feed record from Ulta Beauty, and its answering model
read a rating of 4.5 from 105 reviews for it. ChatGPT also wrote widget cards for three shops, Amazon among them.
AI Mode showed one merchant's listing and a stick version marked `variant`, and put the brand's eye gel in
`otherListings`.

### `summary`

| Field | Description |
| - | - |
| `foundIn`, `notFoundIn` | Engines whose answers showed the product, and engines whose asks finished without showing it. |
| `pending`, `failed` | Engines with asks still running, and engines whose asks all failed. |
| `merchants[]` | Each merchant of the product's listings, with the `engines` that showed it and its single-unit `price` range there, most engines first. |
| `priceRange` | Single-unit prices across engines in the market's currency: USD for `US`, KRW for `KR`. Listings of another pack or form (`match.variant`) are left out. |
| `citedDomains[]` | Each site the answers cite, with the `engines` that cite it, most engines first. |
| `credits` | Credits charged for the product's asks so far. `lookup.credits` covers the whole lookup. |

### `engines[]`

One entry per engine asked:

| Field | Description |
| - | - |
| `status` | The engine's asks together: `QUEUED`, `PROCESSING`, `COMPLETED` once all finished and one completed, or `FAILED` when all failed. |
| `found` | `true` when an answer showed a listing of the product, from a catalog record or a ChatGPT widget card. `false` when every ask finished without one. `null` while asks are still running and nothing is found yet, and when every ask failed. |
| `via[]` | The engine's asks in order, each with the text asked, its `taskId`, `status` and `credits`, and the `error` of a failed ask. |
| `listings[]` | Listings judged to be the product, or another pack or form of it. A listing that two asks both showed appears once. |
| `otherListings[]` | Other products the answers showed. A renamed or translated version of the product can be here. |
| `citedPages[]` | The pages the answers cite, each with `url`, `domain` (the host without `www.` or `m.`), `title` and `ask`. For ChatGPT, these are the sources its answer cites. |

### Listing fields

A listing is one merchant's record of the product as the engine holds it. It carries only the fields the engine
gives.

| Field | Description |
| - | - |
| `position` | Order in the answer, from 1. |
| `ask` | Which of the engine's asks showed it, from 1, in the order of `via[]`. |
| `title` | The product name on the record. On a ChatGPT widget card, the card's heading, which can be the shop's name. |
| `merchant` | Who sells it. |
| `source` | Where the listing comes from. See the next table. |
| `url` | The merchant's page when the engine links one, otherwise the engine's own product page. |
| `price`, `oldPrice` | `value`, `currency` and `raw` as shown. `currency` is an ISO 4217 code when the symbol is unambiguous in the market. `oldPrice` is the price before a discount the engine shows. |
| `available` | Whether it is in stock. ChatGPT only. |
| `rating`, `reviewCount` | The rating and review count on the record. |
| `modelSees` | ChatGPT only: what ChatGPT gave its answering model about the record, its `title`, `description`, `rating`, `reviewCount`, `brand` and `productPage`. A merchant feed record's rating and review count are only here. |
| `image`, `description`, `brand` | As the engine shows them. |
| `reviews` | The review `summary`, `pros` and `cons` the engine shows. |
| `ids` | Catalog identifiers that tie one product's records together, such as `chatgptProductId` and `feedId` on ChatGPT, `googleCatalogId`, `googleProductGroupId` and `googleProductDocId` on Google engines, `bingProductId` and `bingGroupId` on Copilot, and `naverProductId` on Naver AI Tab. No engine returns a GTIN. |
| `pictured` | On a ChatGPT widget card: what the picture beside the card shows, as the answer searched for it. |
| `match` | Why the listing counts as the product. `score` is the share of the product name's words found in the listing, from 0 to 1. `missing` lists the words not found, `variant` marks another pack or form (set, mini, 1+1, stick), and `accessory` a part rather than the product, such as a replacement filter. |

`source` tells you which catalog a listing comes from:

| `source` | Engine | What it is |
| - | - | - |
| `shopify` | ChatGPT | A Shopify store's record in ChatGPT's product catalog |
| `merchant_feed` | ChatGPT | A record from a merchant's product feed to ChatGPT |
| `google_shopping` | ChatGPT, AI Overviews, AI Mode, Gemini | A Google Shopping record |
| `chatgpt_catalog` | ChatGPT | A record in ChatGPT's catalog that does not say where it came from |
| `chatgpt_widget` | ChatGPT | A shop and price ChatGPT wrote in a widget card, with no record behind it |
| `microsoft_shopping` | Copilot | A Microsoft Shopping offer |
| `naver_shopping` | Naver AI Tab | A Naver Shopping listing |

### ChatGPT widget cards

ChatGPT often answers a shopping question with cards that each name a shop and a price it read on the shop's page,
with no catalog record behind them. A lookup reads each card as a `chatgpt_widget` listing after the answer's
records, and counts it toward `found`.

* `merchant` is the shop the card names, or the domain of its buy link. `description` is the card's description
  line.
* A card has no `rating`, `reviewCount`, `available`, `ids` or `modelSees`. A price range such as `$40–$62`
  leaves `price` out.
* A card without a buy link or a seller line is not read.
* A card with the same shop and price as a record or an earlier card of the product is left out. Shops are the
  same when their names or linked sites match or one starts with the other, as with Ulta, Ulta Beauty and ulta.com.

To read catalog records only, leave out the listings whose `source` is `chatgpt_widget`.

## Compare with competitors

An ask about one product rarely shows another brand's product; none did in the 50-product test. So you name the
competitors, and each gets the product's asks. Each entry of `competitors[]` has the competitor's `product`,
`summary` and `engines[]`, read like the product's.

`comparison[]` lines up the product and its competitors, one row per product and one entry per engine. From the
lookup above, trimmed to Copilot, plus ChatGPT for the product:

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

| Field | Description |
| - | - |
| `role` | `product` or `competitor`. |
| `found` | As in `engines[]`. |
| `listings` | Listings judged to be the product, ChatGPT widget cards included. |
| `merchants` | Merchants among those listings. |
| `mostReviewed` | The listing with the most reviews: its `reviewCount`, `rating` and `merchant`. For ChatGPT, the count its answering model was given in `modelSees`. Copilot puts one product's review count on every merchant's offer, so `merchant` is the first offer that carries it. |
| `priceRange` | Single-unit prices on that engine. |
| `prompts` | Only when the lookup has shopper prompts: `answered` is how many of them the engine answered, and `appeared` how many of those answers showed or named the product. |

All three products were found on all four engines. On Copilot, the product's most-reviewed listing has 2,942
reviews, against 85,773 and 117,193 for the two competitors. Across the eight shopper-prompt answers, CeraVe Eye
Repair Cream appeared in five, and the product and Clinique All About Eyes in two each.

## Shopper prompts

Each entry of `prompts[]` has the `prompt` and one entry per engine in `engines[]`:

| Field | Description |
| - | - |
| `shown` | The lookup's products, the product and its competitors, that the answer showed as a record or widget card, in the order shown. |
| `named` | The lookup's products that the answer's text names, in the order named. |
| `listings[]` | Every product record and widget card in the answer. One that is a looked-up product carries `product` and `match`. |
| `via[]`, `citedPages[]` | As in `engines[]`. |

An answer to a shopper prompt shows many brands' products, so a record counts as one of the lookup's products only
when it contains the brand, the first word of the product name. A name in the text counts the way a
[GEO monitor](/monitors.md) counts a brand mention, with the product's full name as the term.

From the lookup above, AI Overviews and Copilot answering `best moisturizing eye cream`, with listings trimmed to
the lookup's products:

```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 named the product in its text but showed records of the two competitors only. Copilot showed the
product from three merchants. Matching uses names, so a version whose name adds a word, such as
`Clinique All About Eyes Rich`, counts as the product.

## Send a lookup again

Each ask has its own key, made from the lookup id:

* The product's asks: `<id>:<engine>:<ask>`, such as `eye-bomb-us:CHATGPT:buy`. ChatGPT's asks are `buy` and
  `price`, and the other engines' ask is `name`.
* The nth competitor's asks add `:c<n>`, such as `eye-bomb-us:CHATGPT:buy:c1`.
* The nth prompt's asks: `<id>:<engine>:p<n>`, such as `eye-bomb-us:AIMODE:p1`.

Sending a lookup again under the same `idempotencyKey` returns the asks that exist and adds only the missing ones,
and you are charged only for the asks it adds. Use it to finish a lookup whose asks were refused for credits or
concurrency, or to add a competitor or prompt at the end of its list. A competitor or prompt you leave out stays in
the lookup.

A resend that changes the product or the country, or puts a different competitor or prompt in a position that
already holds one, returns `409 RESOURCE_ALREADY_EXISTS` and writes nothing. A resend returns an ask that failed as
it is. To ask the engines again for fresh answers, send the lookup under a new `idempotencyKey`.

## Pricing

A lookup costs 10 credits for each product, the product and each competitor, and 5 credits for each shopper prompt,
whichever engines you ask.

* The lookup above costs 3 × 10 + 2 × 5 = 40 credits. The largest lookup, a product with 5 competitors and 3
  prompts, costs 75 credits.
* A product's or prompt's credits are split over its asks. On the `US` defaults, a product ask is 2 credits and a
  prompt ask 1.25. On the `KR` defaults, a product ask is 2.5 credits and a prompt's three asks are 1.67, 1.67 and
  1.66. Asking fewer engines does not lower the price: on ChatGPT alone, each of a product's two asks is 5 credits.
* Each ask is held at submit and charged when it completes, like any task. An ask that fails is not charged.
* At plan prices, a product costs \$0.025 on Basic and \$0.010 on Max.

See [Credits and limits](/concepts/credits-and-limits.md) for holds and plans.

## Reading the results correctly

* **One lookup is one snapshot.** Each engine answers one or two asks. Before you act on a single difference, run
  the lookup again under a new `idempotencyKey`.
* **Records keep their values; the selection changes.** In four runs of one lookup, the same merchant record kept
  its price, rating and review count in 307 of 316 values. What changes from run to run is which records an answer
  shows, so `found` (most often on ChatGPT), the merchants, `mostReviewed`, `priceRange` and the prompts' `shown`
  and `named` can differ.
* **Minutes apart varies as much as hours apart.** ChatGPT, AI Mode and Copilot answers differed as much three
  minutes apart as eleven hours apart. AI Overviews asked again within seconds can return the same answer, so a
  quick repeat there is not a new sample.
* **Totals are steadier than single answers.** Across the four runs, single shopper-prompt answers changed, but the
  products that appeared in the most answers led in every run. To follow prompts over time, track them with a
  [GEO monitor](/monitors.md).
* **`found: false` describes these answers.** It means this run's asks did not show the product. It does not mean
  the engine's catalog lacks it.
* **Matching uses names.** No engine returns a GTIN. A renamed or translated product can land in `otherListings`,
  and a version its name does not tell apart can count as the product. Check `match` when a listing looks off.

## Limits

* The input is a product name. Product page URLs and GTINs are not supported.
* The markets are `US` and `KR`.
* A lookup takes up to 5 competitors and 3 shopper prompts. On the `US` defaults, the largest lookup makes 42
  asks.
* The competitors are the ones you name. A lookup does not find them for you; shopper prompts show which products
  an engine puts in front of shoppers.
* ChatGPT's records and widget cards are read. Shops and prices it writes in the answer's text or tables are not.
* Each answer contributes up to 60 listings and 20 cited pages.
* A lookup can be read while its asks' tasks can, until 24 hours after they complete. See
  [Async tasks](/concepts/async-tasks.md#retention).

## Errors

### Rejected at submit

| Status | Code | Cause |
| - | - | - |
| `400` | `VALIDATION_ERROR` | The body is not valid JSON, or a field breaks a rule above: a missing `product` or `country`, a URL or GTIN as a name, too many or duplicate `competitors` or `prompts`, an unknown engine or one not offered in the market, or an invalid `idempotencyKey`. `details` names the field. |
| `422` | `REGION_UNSUPPORTED` | `country` is not `US` or `KR`. |
| `409` | `RESOURCE_ALREADY_EXISTS` | The `idempotencyKey` names a lookup of another product or country, or one with a different competitor or prompt in the same position. Nothing was written. |

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

### Refused asks

Each ask is admitted like a single task, so it can be refused for your balance (`402 INSUFFICIENT_CREDITS`), your
plan's concurrency (`429 PLAN_CONCURRENCY_LIMIT`), a key's daily credit limit (`429 KEY_DAILY_CREDIT_LIMIT`) or a
key limited to other engines. A refused ask stays in `asks[]` with `success: false` and its `error`, and the other
asks go ahead.

Asks are admitted one at a time: every engine's first ask about each product, and each prompt, before any second
ask. So when your plan has room for only some of the asks, the admitted ones cover as many engines and products as they can. When none of
the product's first asks is admitted, nothing else is asked, and the response is the first refusal with its status,
such as `402 INSUFFICIENT_CREDITS`. On the Free plan's 2 concurrent tasks, a `US` lookup admits the product's
first ChatGPT and AI Overviews asks; send it again when they finish to add the rest. The largest `US` lookup, 42
asks, fits Basic's 50 concurrent tasks when nothing else is queued.

Authentication errors are the same as for any request. See [Errors](/concepts/errors.md).

### Failed asks and reads

* An ask that fails has `status: "FAILED"` and an `error` in `via[]`, and is not charged. An engine whose asks all
  failed has `status: "FAILED"` and `found: null`, and is listed in `summary.failed`.
* `GET /v1/product-lookup/{id}` returns `404 RESOURCE_NOT_FOUND` for an id with no lookup on your account,
  including one whose tasks are past the read window.

## Next steps

> **[GEO monitors](/monitors.md)**
>
> Track shopper prompts across AI engines on a schedule.

> **[Prompt Research](/research/prompt-research.md)**
>
> Find the shopping questions people ask about a category.


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