> ## 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：查看 AI 购物引擎如何展示一个商品

> 向 ChatGPT、Google AI 概览、AI 模式、Copilot 和 Naver AI 标签页询问一个商品，逐个引擎查看回答是否展示了它、用了哪些商家的商品条目、引用了哪些页面。

用 Product Lookup 以购物者看到的方式查看一个商品在 AI 购物引擎中的样子。发送商品名称和市场，querying.ai 就会向每个引擎询问这个商品。对每个引擎，你会知道回答是否展示了该商品、展示了哪些商家的商品条目（商家、目录、价格、库存、评分和评论数），以及回答引用了哪些页面。最多可加入 5 个竞品，逐个引擎比较；也可加入最多 3 个购物提示词，例如 `best moisturizing eye cream`，查看每个引擎会向购物者展示其中哪些商品。

一次查询可以回答这些问题：

* 询问 ChatGPT、Google AI 概览、AI 模式或 Copilot 时，它们会展示这个商品吗？
* 每个引擎通过哪些商家和目录记录展示它，价格多少，评分和评论数如何？
* ChatGPT 的回答模型读到了关于这个商品的哪些信息？
* 在每个引擎上，这个商品与竞品相比如何？
* 面对一个购物问题，每个引擎会展示其中哪些商品？

## 提交查询

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

查询会拆成多次提问：每次提问都是就一个商品或一个提示词向一个引擎发问。每次提问都作为普通任务排队，响应会把它们列出来。下面只保留了 23 次提问中的 3 次：

```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` 是你的 `idempotencyKey`；不传时由服务器生成一个 UUID。读取查询时要用它。
* `asks[]` 的每一项包含 `role`（`product`、`competitor` 或 `prompt`）、写在 `prompt` 或 `query` 中的提问文本，以及对应的 `task`。被拒绝的提问没有 `task`，而是带有 `success: false` 和 `error`。见[错误](#错误)。
* `credits.creditsToCharge` 是响应中各次提问价格的总和，在每次提问结束前从余额中冻结。`creditsCharged` 是这些提问已经扣除的积分。

用 `GET /v1/product-lookup/{id}` 读取查询，直到 `lookup.status` 变为 `COMPLETED`。这次查询用了大约两分钟；查询在最慢的引擎回答后结束。设置 `webhook.url` 后，每次提问的任务结束时都会推送给你，`task.idempotencyKey` 中是这次提问的键，以查询 id 开头。没有覆盖整个查询的 webhook，所以每次收到推送时，请读取查询并检查 `lookup.status`。Schema 见 API 参考：[Product Lookup](/zh/api-reference/product-lookup.md) 和[获取 Product Lookup 结果](/zh/api-reference/get-product-lookup.md)。

## 请求字段

| 字段 | 必填 | 说明 |
| - | - | - |
| `product` | 是 | 购物者常用的商品名称，1–200 个字符，例如 `belif Moisturizing Eye Bomb`。传入商品页 URL 或 GTIN 会返回 `400 VALIDATION_ERROR`。 |
| `country` | 是 | `US`（美国）或 `KR`（韩国），不区分大小写。其他值返回 `422 REGION_UNSUPPORTED`。 |
| `competitors` | 否 | 最多 5 个其他商品的名称，规则与 `product` 相同。每个竞品都会得到与商品相同的提问。与商品同名或重复列出的名称返回 `400`。只在大小写、标点或空格上不同的名称视为相同。 |
| `prompts` | 否 | 最多 3 个购物提示词，每个 1–300 个字符，例如 `best moisturizing eye cream`。每个提示词按原文向每个引擎问一次。 |
| `engines` | 否 | 要询问的引擎：`CHATGPT`、`GOOGLE`、`AIMODE`、`BING_COPILOT`、`GEMINI`，以及仅限 `KR` 的 `NAVER_AI_TAB`。默认使用下文所列该市场的引擎。 |
| `idempotencyKey` | 否 | 查询的名称：1–200 个字符，首尾不能有空格。见[再次发送](#再次发送)。 |
| `priority` | 否 | 整数 `1`–`10`，默认 `1`，设置在每次提问上。超出范围的值会被截到边界。它不保证执行顺序。 |
| `webhook.url` | 否 | 每次提问的任务结束时接收该任务。见 [Webhooks](/zh/concepts/webhooks.md)。 |

## 引擎与提问

商品和每个竞品得到相同的提问：

| 引擎 | `US` | `KR` |
| - | - | - |
| `CHATGPT` | `Buy {product}` 和 `Find the best price for {product}` | `{product} 구매` 和 `{product} 최저가` |
| `GOOGLE`（Google AI 概览） | 商品名称 | 商品名称，按需 |
| `AIMODE`（Google AI 模式） | 商品名称 | 商品名称 |
| `BING_COPILOT`（Copilot） | 商品名称 | 商品名称，按需 |
| `NAVER_AI_TAB`（Naver AI 标签页） | 不可用 | 商品名称 |
| `GEMINI` | 商品名称，按需 | 商品名称，按需 |

“按需”指只有在 `engines` 中列出该引擎时才会询问它。不传 `engines` 时，`US` 查询询问 ChatGPT、AI 概览、AI 模式和 Copilot，每个商品 5 次提问；`KR` 查询询问 Naver AI 标签页、ChatGPT 和 AI 模式，每个商品 4 次提问。购物提示词向每个引擎各问一次：使用 `US` 默认引擎时 4 次，使用 `KR` 默认引擎时 3 次。上面的查询共有 3 × 5 + 2 × 4 = 23 次提问。

ChatGPT 问两次，是因为一次提问只对大约一半的商品展示商品记录，而同一提问重复时常常命中另一半。其他默认引擎是在 2026-10-20 对 50 个商品的测试中展示了商品的引擎：

| 引擎 | `US` | `KR` |
| - | - | - |
| ChatGPT（两次提问，含小组件卡片） | 24 次查询中 24 次 | 20 次查询中 20 次 |
| Copilot | 25 次中 25 次 | 25 次中 0 次 |
| Google AI 概览 | 25 次中 23 次 | 25 次中 1 次 |
| Google AI 模式 | 25 次中 23 次 | 25 次中 13 次 |
| Naver AI 标签页 | – | 25 次中 25 次 |

ChatGPT 一行来自 12 个 `US` 商品和 10 个 `KR` 商品，每个商品查询两次。在两个市场的 115 次提问中，Gemini 没有展示任何商品记录。

## 读取查询

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

结果分为五部分：

* `lookup`：问了什么、`status`，以及目前已扣除的 `credits`。
* `summary` 和 `engines[]`：关于该商品的回答，先跨引擎汇总，再逐个引擎列出。
* `competitors[]`：每个竞品同样的 `summary` 和 `engines[]`。
* `comparison[]`：逐个引擎并排列出商品和竞品。
* `prompts[]`：每个引擎对每个购物提示词的回答。

在任何提问开始前，`lookup.status` 为 `QUEUED`；只要还有提问未结束，就是 `PROCESSING`。所有提问都结束且至少一次完成后变为 `COMPLETED`，全部失败时为 `FAILED`。各项会随提问结束陆续填入，所以查询完成前也可以读取。

下面是上述查询的 `lookup`、`summary` 和 `engines[]`，只保留四个引擎中的两个，每个列表只留几项：

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

四个引擎都展示了该商品。ChatGPT 展示了 Ulta Beauty 的一条商家数据源记录，它的回答模型读到这条记录的评分为 4.5，来自 105 条评论。ChatGPT 还为三家店铺写了小组件卡片，其中包括 Amazon。AI 模式展示了一个商家的商品条目和一个标为 `variant` 的棒状版本，并把同品牌的眼部凝胶放进了 `otherListings`。

### `summary`

| 字段 | 说明 |
| - | - |
| `foundIn`、`notFoundIn` | 回答展示了该商品的引擎，以及提问已结束但没有展示它的引擎。 |
| `pending`、`failed` | 仍有提问在运行的引擎，以及提问全部失败的引擎。 |
| `merchants[]` | 该商品条目中的每个商家，附展示它的 `engines` 和它在这些引擎上的单件 `price` 区间，出现在越多引擎上的商家越靠前。 |
| `priceRange` | 各引擎上的单件价格，以该市场的货币计：`US` 为 USD，`KR` 为 KRW。其他规格或形态的条目（`match.variant`）不计入。 |
| `citedDomains[]` | 回答引用的每个网站，附引用它的 `engines`，被越多引擎引用的网站越靠前。 |
| `credits` | 该商品的提问目前已扣除的积分。整个查询的积分见 `lookup.credits`。 |

### `engines[]`

每个被询问的引擎一项：

| 字段 | 说明 |
| - | - |
| `status` | 该引擎所有提问的整体状态：`QUEUED`、`PROCESSING`；全部结束且至少一次完成时为 `COMPLETED`，全部失败时为 `FAILED`。 |
| `found` | 回答展示了该商品的条目（来自目录记录或 ChatGPT 小组件卡片）时为 `true`。所有提问都已结束却没有展示时为 `false`。提问仍在运行且尚未找到时，以及所有提问都失败时，为 `null`。 |
| `via[]` | 该引擎的各次提问，按顺序列出，每项包含提问文本、`taskId`、`status` 和 `credits`，失败的提问还带有 `error`。 |
| `listings[]` | 判定为该商品或其其他规格、形态的条目。两次提问都展示的条目只出现一次。 |
| `otherListings[]` | 回答展示的其他商品。改名或翻译过的商品版本可能出现在这里。 |
| `citedPages[]` | 回答引用的页面，每项包含 `url`、`domain`（去掉 `www.` 或 `m.` 的主机名）、`title` 和 `ask`。对 ChatGPT 来说，就是其回答引用的来源。 |

### 商品条目字段

一个商品条目是引擎中某个商家对该商品的记录，只包含引擎提供的字段。

| 字段 | 说明 |
| - | - |
| `position` | 在回答中的顺序，从 1 开始。 |
| `ask` | 该引擎的第几次提问展示了它，从 1 开始，顺序同 `via[]`。 |
| `title` | 记录上的商品名称。在 ChatGPT 小组件卡片上是卡片标题，可能是店铺名称。 |
| `merchant` | 销售方。 |
| `source` | 条目的来源，见下表。 |
| `url` | 引擎链接了商家页面时为商家页面，否则为引擎自己的商品页。 |
| `price`、`oldPrice` | `value`、`currency`，以及按原样显示的 `raw`。货币符号在该市场没有歧义时，`currency` 为 ISO 4217 代码。`oldPrice` 是引擎显示的折扣前价格。 |
| `available` | 是否有货。仅 ChatGPT。 |
| `rating`、`reviewCount` | 记录上的评分和评论数。 |
| `modelSees` | 仅 ChatGPT：ChatGPT 向回答模型提供的这条记录的信息，包括 `title`、`description`、`rating`、`reviewCount`、`brand` 和 `productPage`。商家数据源记录的评分和评论数只出现在这里。 |
| `image`、`description`、`brand` | 与引擎显示的一致。 |
| `reviews` | 引擎显示的评论 `summary`、`pros` 和 `cons`。 |
| `ids` | 把同一商品的各条记录关联起来的目录标识，例如 ChatGPT 的 `chatgptProductId` 和 `feedId`，Google 引擎的 `googleCatalogId`、`googleProductGroupId` 和 `googleProductDocId`，Copilot 的 `bingProductId` 和 `bingGroupId`，以及 Naver AI 标签页的 `naverProductId`。没有引擎返回 GTIN。 |
| `pictured` | 仅 ChatGPT 小组件卡片：卡片旁图片展示的内容，即回答搜索这张图片时写下的描述。 |
| `match` | 判定该条目属于该商品的依据。`score` 是商品名称中的词在条目里出现的比例，从 0 到 1。`missing` 列出没有出现的词，`variant` 标记其他规格或形态（套装、迷你装、1+1、棒状），`accessory` 标记配件而非商品本身，例如替换滤芯。 |

`source` 表示条目来自哪个目录：

| `source` | 引擎 | 含义 |
| - | - | - |
| `shopify` | ChatGPT | ChatGPT 商品目录中某家 Shopify 店铺的记录 |
| `merchant_feed` | ChatGPT | 来自商家提交给 ChatGPT 的商品数据源的记录 |
| `google_shopping` | ChatGPT、AI 概览、AI 模式、Gemini | Google Shopping 记录 |
| `chatgpt_catalog` | ChatGPT | ChatGPT 目录中未注明来源的记录 |
| `chatgpt_widget` | ChatGPT | ChatGPT 在小组件卡片中写出的店铺和价格，背后没有记录 |
| `microsoft_shopping` | Copilot | Microsoft Shopping 报价 |
| `naver_shopping` | Naver AI 标签页 | Naver Shopping 商品条目 |

### ChatGPT 小组件卡片

ChatGPT 回答购物问题时常用卡片，每张卡片写着一家店铺和它从店铺页面读到的价格，背后没有目录记录。查询会在回答中的记录之后，把每张卡片读成一条 `chatgpt_widget` 条目，并计入 `found`。

* `merchant` 是卡片写明的店铺，或其购买链接的域名。`description` 是卡片的描述行。
* 卡片没有 `rating`、`reviewCount`、`available`、`ids` 或 `modelSees`。价格是 `$40–$62` 这样的区间时，不填 `price`。
* 既没有购买链接、也没有卖家行的卡片不会被读取。
* 店铺和价格都与该商品的某条记录或之前某张卡片相同的卡片不计入。名称或链接的网站相同，或一方以另一方开头时，视为同一店铺，例如 Ulta、Ulta Beauty 和 ulta.com。

只看目录记录时，去掉 `source` 为 `chatgpt_widget` 的条目即可。

## 与竞品比较

关于一个商品的提问很少展示其他品牌的商品，在 50 个商品的测试中一次也没有。所以竞品要由你指定，每个竞品都会得到与商品相同的提问。`competitors[]` 的每一项包含竞品的 `product`、`summary` 和 `engines[]`，读法与商品相同。

`comparison[]` 把商品和竞品排在一起：每个商品一行，每个引擎一项。下面来自上述查询，只保留 Copilot，商品另加 ChatGPT：

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

| 字段 | 说明 |
| - | - |
| `role` | `product` 或 `competitor`。 |
| `found` | 同 `engines[]`。 |
| `listings` | 判定为该商品的条目数，含 ChatGPT 小组件卡片。 |
| `merchants` | 这些条目涉及的商家数。 |
| `mostReviewed` | 评论最多的条目：它的 `reviewCount`、`rating` 和 `merchant`。对 ChatGPT 来说，是 `modelSees` 中提供给回答模型的评论数。Copilot 会把同一个商品的评论数放在每个商家的报价上，所以 `merchant` 是第一个带有该评论数的报价。 |
| `priceRange` | 该引擎上的单件价格。 |
| `prompts` | 仅当查询包含购物提示词时出现：`answered` 是该引擎回答了其中几个提示词，`appeared` 是这些回答中有几个展示或提到了该商品。 |

三个商品在四个引擎上都被找到了。在 Copilot 上，该商品评论最多的条目有 2,942 条评论，两个竞品分别为 85,773 条和 117,193 条。在 8 个购物提示词回答中，CeraVe Eye Repair Cream 出现在 5 个回答里，该商品和 Clinique All About Eyes 各出现在 2 个回答里。

## 购物提示词

`prompts[]` 的每一项包含 `prompt`，以及 `engines[]` 中每个引擎一项：

| 字段 | 说明 |
| - | - |
| `shown` | 回答以记录或小组件卡片形式展示的本次查询商品（商品和竞品），按展示顺序排列。 |
| `named` | 回答正文提到的本次查询商品，按提到的顺序排列。 |
| `listings[]` | 回答中的每条商品记录和每张小组件卡片。属于本次查询商品的条目带有 `product` 和 `match`。 |
| `via[]`、`citedPages[]` | 同 `engines[]`。 |

购物提示词的回答会展示许多品牌的商品，所以只有包含品牌（即商品名称的第一个词）的记录，才算作本次查询的商品。正文中的名称按照 [GEO 监测器](/zh/monitors.md)统计品牌提及的方式计数，以商品全名作为检索词。

下面是上述查询中 AI 概览和 Copilot 对 `best moisturizing eye cream` 的回答，条目只保留本次查询的商品：

```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 概览在正文中提到了该商品，但只展示了两个竞品的记录。Copilot 通过三个商家展示了该商品。匹配基于名称，所以名称多出一个词的版本（例如 `Clinique All About Eyes Rich`）也会算作对应的商品。

## 再次发送

每次提问都有自己的键，由查询 id 构成：

* 商品的提问：`<id>:<engine>:<ask>`，例如 `eye-bomb-us:CHATGPT:buy`。ChatGPT 的提问是 `buy` 和 `price`，其他引擎的提问是 `name`。
* 第 n 个竞品的提问在末尾加上 `:c<n>`，例如 `eye-bomb-us:CHATGPT:buy:c1`。
* 第 n 个提示词的提问：`<id>:<engine>:p<n>`，例如 `eye-bomb-us:AIMODE:p1`。

用同一个 `idempotencyKey` 再次发送查询，会返回已有的提问，只添加缺少的提问，也只对新添加的提问收费。可以用它补完因积分或并发被拒绝的提问，或在列表末尾添加竞品或提示词。再次发送时省略的竞品或提示词仍保留在查询中。

如果再次发送时改了商品或国家，或在已有竞品或提示词的位置放了另一个竞品或提示词，会返回 `409 RESOURCE_ALREADY_EXISTS`，且不写入任何内容。失败的提问在再次发送时原样返回。要让引擎重新回答，请用新的 `idempotencyKey` 发送查询。

## 价格

商品和每个竞品各 10 积分，每个购物提示词 5 积分，与询问哪些引擎无关。

* 上面的查询是 3 × 10 + 2 × 5 = 40 积分。最大的查询（一个商品加 5 个竞品和 3 个提示词）是 75 积分。
* 一个商品或提示词的积分分摊到它的各次提问上。使用 `US` 默认引擎时，商品的每次提问 2 积分，提示词的每次提问 1.25 积分。使用 `KR` 默认引擎时，商品的每次提问 2.5 积分，提示词的三次提问分别为 1.67、1.67 和 1.66 积分。少问几个引擎不会降低价格：只问 ChatGPT 时，商品的两次提问各 5 积分。
* 和其他任务一样，每次提问在提交时冻结，完成时扣除。失败的提问不扣费。
* 按套餐价格计算，一个商品在 Basic 上为 \$0.025，在 Max 上为 \$0.010。

冻结和套餐见[积分与限制](/zh/concepts/credits-and-limits.md)。

## 正确解读结果

* **一次查询是一次快照。** 每个引擎只回答一两次提问。根据单个差异采取行动前，请用新的 `idempotencyKey` 再跑一次查询。
* **记录的值稳定，被选中的记录会变。** 同一查询跑了四次，同一商家记录的价格、评分和评论数在 316 个值中有 307 个保持不变。每次运行会变的是回答展示哪些记录，因此 `found`（以 ChatGPT 最常见）、商家、`mostReviewed`、`priceRange` 以及提示词的 `shown` 和 `named` 都可能不同。
* **相隔几分钟与相隔几小时变化一样大。** ChatGPT、AI 模式和 Copilot 的回答，相隔三分钟与相隔十一小时的差异一样大。AI 概览在几秒内重问可能返回同一个回答，所以在它上面快速重复不算新的样本。
* **汇总比单个回答更稳定。** 四次运行中，单个购物提示词的回答各有变化，但出现在最多回答中的商品每次都领先。要长期跟踪提示词，请使用 [GEO 监测器](/zh/monitors.md)。
* **`found: false` 只描述这些回答。** 它表示本次运行的提问没有展示该商品，并不表示引擎的目录里没有它。
* **匹配基于名称。** 没有引擎返回 GTIN。改名或翻译过的商品可能落在 `otherListings` 中，名称上区分不出的版本也可能算作该商品。条目看起来不对时，请检查 `match`。

## 限制

* 输入是商品名称，不支持商品页 URL 和 GTIN。
* 市场为 `US` 和 `KR`。
* 一次查询最多包含 5 个竞品和 3 个购物提示词。使用 `US` 默认引擎时，最大的查询有 42 次提问。
* 竞品由你指定，查询不会替你寻找竞品；购物提示词能显示引擎把哪些商品摆在购物者面前。
* 读取 ChatGPT 的记录和小组件卡片，不读取它在回答正文或表格中写出的店铺和价格。
* 每个回答最多贡献 60 个商品条目和 20 个引用页面。
* 只要查询的提问任务还能读取，就能读取查询，即完成后 24 小时内。见[异步任务](/zh/concepts/async-tasks.md#保留期)。

## 错误

### 提交时被拒绝

| 状态 | 错误码 | 原因 |
| - | - | - |
| `400` | `VALIDATION_ERROR` | 请求体不是有效的 JSON，或某个字段违反上述规则：缺少 `product` 或 `country`，名称是 URL 或 GTIN，`competitors` 或 `prompts` 过多或重复，引擎未知或该市场不提供，或 `idempotencyKey` 无效。`details` 会指出字段。 |
| `422` | `REGION_UNSUPPORTED` | `country` 不是 `US` 或 `KR`。 |
| `409` | `RESOURCE_ALREADY_EXISTS` | 该 `idempotencyKey` 对应的查询属于另一个商品或国家，或在同一位置上有不同的竞品或提示词。没有写入任何内容。 |

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

### 被拒绝的提问

每次提问都像单个任务一样接受准入检查，所以可能因余额（`402 INSUFFICIENT_CREDITS`）、套餐并发（`429 PLAN_CONCURRENCY_LIMIT`）、密钥的每日积分上限（`429 KEY_DAILY_CREDIT_LIMIT`），或密钥只允许其他引擎而被拒绝。被拒绝的提问以 `success: false` 和对应的 `error` 留在 `asks[]` 中，其他提问照常进行。

提问逐个接受准入：先是每个引擎对每个商品的第一次提问以及每个提示词，然后才是任何第二次提问。因此，当套餐只容得下部分提问时，被接受的提问会尽量覆盖更多引擎和商品。如果商品的第一次提问一个都没被接受，就不会再发出任何提问，响应就是第一个拒绝及其状态码，例如 `402 INSUFFICIENT_CREDITS`。在 Free 套餐的 2 个并发任务下，`US` 查询会接受商品在 ChatGPT 和 AI 概览上的第一次提问；等它们结束后再次发送，即可添加其余提问。最大的 `US` 查询有 42 次提问，在没有其他任务排队时，可以放进 Basic 套餐的 50 个并发任务。

认证错误与其他请求相同。见[错误](/zh/concepts/errors.md)。

### 失败的提问与读取

* 失败的提问在 `via[]` 中为 `status: "FAILED"` 并带有 `error`，不扣费。提问全部失败的引擎为 `status: "FAILED"` 和 `found: null`，并列在 `summary.failed` 中。
* 如果你的账户下没有该 id 的查询，包括任务已超出读取期限的查询，`GET /v1/product-lookup/{id}` 返回 `404 RESOURCE_NOT_FOUND`。

## 后续步骤

> **[GEO 监测](/zh/monitors.md)**
>
> 按计划在各 AI 引擎上跟踪购物提示词。

> **[Prompt Research](/zh/research/prompt-research.md)**
>
> 找出人们围绕某个品类提出的购物问题。


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