> ## 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, 네이버 AI 탭에 상품을 묻고, 엔진마다 답변이 상품을 보여줬는지, 어떤 판매처 리스팅을 썼는지, 어느 페이지를 인용했는지 확인합니다.

Product Lookup은 AI 쇼핑 엔진이 쇼핑하는 사람에게 상품을 어떻게 보여주는지 확인할 때 씁니다. 상품 이름과 시장을
보내면 querying.ai가 엔진마다 그 상품을 묻습니다. 엔진별로 답변이 상품을 보여줬는지, 어떤 판매처 리스팅(판매처,
카탈로그, 가격, 재고, 평점과 리뷰 수)을 보여줬는지, 답변이 어느 페이지를 인용했는지 돌려줍니다. 경쟁 상품을 5개까지
넣으면 엔진별로 나란히 비교하고, `best moisturizing eye cream` 같은 쇼핑 질문을 3개까지 넣으면 엔진마다 이 상품들
가운데 무엇을 보여주는지 볼 수 있습니다.

조회 한 번으로 다음을 확인할 수 있습니다.

* 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`는 그 질문들에 이미 차감된 크레딧입니다.

`lookup.status`가 `COMPLETED`가 될 때까지 `GET /v1/product-lookup/{id}`로 조회 결과를 읽습니다. 이 조회는 약 2분
걸렸습니다. 조회는 가장 느린 엔진이 답할 때 끝납니다. `webhook.url`을 넣으면 질문마다 태스크가 끝날 때 전송되고,
`task.idempotencyKey`에는 조회 id로 시작하는 그 질문의 key가 담깁니다. 조회 전체가 끝났다는 webhook은 없으므로
받을 때마다 조회 결과를 읽어 `lookup.status`를 확인하세요. 스키마는 API 레퍼런스의
[Product Lookup](/ko/api-reference/product-lookup.md)과 [Product Lookup 결과 조회](/ko/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` | 아니요 | 1–300자의 쇼핑 질문 최대 3개. 예: `best moisturizing eye cream`. 쓴 그대로 엔진마다 한 번 묻습니다. |
| `engines` | 아니요 | 물을 엔진: `CHATGPT`, `GOOGLE`, `AIMODE`, `BING_COPILOT`, `GEMINI`, 그리고 `KR`에서만 `NAVER_AI_TAB`. 없으면 아래 시장별 기본 엔진에 묻습니다. |
| `idempotencyKey` | 아니요 | 조회의 이름. 앞뒤 공백이 없는 1–200자입니다. [다시 보내기](#다시-보내기)를 참고하세요. |
| `priority` | 아니요 | 정수 `1`–`10`, 기본값 `1`이며 모든 질문에 붙습니다. 범위를 벗어난 값은 범위 안으로 맞춥니다. 실행 순서를 보장하지 않습니다. |
| `webhook.url` | 아니요 | 질문마다 태스크가 끝나면 받습니다. [Webhook](/ko/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`(네이버 AI 탭) | 지원하지 않음 | 상품 이름 |
| `GEMINI` | 상품 이름, 요청 시 | 상품 이름, 요청 시 |

"요청 시"는 `engines`에 넣었을 때만 묻는다는 뜻입니다. `engines`가 없으면 `US` 조회는 ChatGPT, AI 개요, AI 모드,
Copilot에 묻고 상품마다 질문이 5개입니다. `KR` 조회는 네이버 AI 탭, ChatGPT, AI 모드에 묻고 상품마다 질문이
4개입니다. 쇼핑 질문은 엔진마다 한 번 묻으므로 `US` 기본 엔진에서 4개, `KR` 기본 엔진에서 3개입니다. 위 조회의
질문은 3 × 5 + 2 × 4 = 23개였습니다.

ChatGPT에 두 번 묻는 이유는 질문 하나로는 상품의 절반 정도에서만 상품 기록이 나오고, 같은 질문을 다시 하면 다른
절반에서 나오는 경우가 많기 때문입니다. 나머지 기본 엔진은 2026-10-20에 상품 50개로 시험했을 때 상품을 보여준
엔진입니다.

| 엔진 | `US` | `KR` |
| - | - | - |
| ChatGPT, 질문 2개, 위젯 카드 포함 | 조회 24회 중 24회 | 조회 20회 중 20회 |
| Copilot | 25개 중 25개 | 25개 중 0개 |
| Google AI 개요 | 25개 중 23개 | 25개 중 1개 |
| Google AI 모드 | 25개 중 23개 | 25개 중 13개 |
| 네이버 AI 탭 | – | 25개 중 25개 |

ChatGPT 행은 `US` 상품 12개와 `KR` 상품 10개를 두 번씩 조회한 결과입니다. Gemini는 두 시장에서 질문 115개를
받는 동안 상품 기록을 하나도 보여주지 않았습니다.

## 조회 결과 읽기

```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[]`입니다. 엔진 4개 중 2개와 목록마다 항목 몇 개만 남겼습니다.

```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` | 답변이 상품의 리스팅을 보여줬으면 `true`입니다. 카탈로그 기록과 ChatGPT 위젯 카드를 모두 셉니다. 모든 질문이 끝났는데 없으면 `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`, 네이버 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` | 네이버 AI 탭 | 네이버 쇼핑 리스팅 |

### 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 모니터](/ko/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로 만든 key가 있습니다.

* 상품의 질문: `<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입니다.

보류와 요금제는 [크레딧과 한도](/ko/concepts/credits-and-limits.md)를 참고하세요.

## 결과를 올바르게 읽기

* **조회 한 번은 한 시점의 기록입니다.** 엔진마다 질문 한두 개에 답합니다. 한 번 나온 차이로 결정하기 전에 새
  `idempotencyKey`로 다시 조회하세요.
* **기록의 값은 그대로이고, 어떤 기록이 나오는지가 바뀝니다.** 같은 조회를 네 번 실행했을 때 같은 판매처 기록의
  가격, 평점, 리뷰 수는 316개 값 중 307개가 같았습니다. 실행마다 바뀌는 것은 답변이 어떤 기록을 보여주는지입니다.
  그래서 `found`(특히 ChatGPT), 판매처, `mostReviewed`, `priceRange`, 쇼핑 질문의 `shown`과 `named`가 달라질 수
  있습니다.
* **몇 분 간격도 몇 시간 간격만큼 다릅니다.** ChatGPT, AI 모드, Copilot의 답변은 3분 간격일 때도 11시간 간격일
  때만큼 달랐습니다. AI 개요는 몇 초 안에 다시 물으면 같은 답변이 나올 수 있으므로, 곧바로 다시 물은 결과는 새 표본이
  아닙니다.
* **답변 하나보다 합계가 안정적입니다.** 네 번의 실행에서 쇼핑 질문 답변 하나하나는 바뀌었지만, 가장 많은 답변에
  나온 상품들은 매번 앞섰습니다. 쇼핑 질문을 시간에 따라 추적하려면 [GEO 모니터](/ko/monitors.md)를 쓰세요.
* **`found: false`는 이번 답변에 대한 결과입니다.** 이번 실행의 질문들이 상품을 보여주지 않았다는 뜻입니다. 엔진의
  카탈로그에 상품이 없다는 뜻은 아닙니다.
* **판정은 이름으로 합니다.** GTIN을 주는 엔진은 없습니다. 이름이 바뀌었거나 번역된 상품은 `otherListings`에 들어갈
  수 있고, 이름으로 구분되지 않는 버전은 그 상품으로 셀 수 있습니다. 리스팅이 이상해 보이면 `match`를 확인하세요.

## 제한 사항

* 입력은 상품 이름입니다. 상품 페이지 URL과 GTIN은 지원하지 않습니다.
* 시장은 `US`와 `KR`입니다.
* 조회 하나에 경쟁 상품 5개와 쇼핑 질문 3개까지 넣을 수 있습니다. `US` 기본 엔진에서 가장 큰 조회는 질문 42개입니다.
* 경쟁 상품은 직접 넣은 것만 봅니다. 조회가 경쟁 상품을 찾아 주지는 않습니다. 엔진이 쇼핑하는 사람에게 어떤 상품을
  보여주는지는 쇼핑 질문으로 확인합니다.
* ChatGPT는 기록과 위젯 카드를 읽습니다. 답변 본문이나 표에 쓴 판매처와 가격은 읽지 않습니다.
* 답변 하나에서 리스팅은 60개, 인용 페이지는 20개까지 담습니다.
* 조회 결과는 질문 태스크를 읽을 수 있는 동안, 곧 완료 후 24시간까지 읽을 수 있습니다.
  [비동기 태스크](/ko/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`가 그 예입니다.
동시 실행이 2개인 Free 요금제에서 `US` 조회는 상품의 ChatGPT 첫 질문과 AI 개요 질문만 들어갑니다. 이 질문들이 끝난
뒤 다시 보내면 나머지가 들어갑니다. 가장 큰 `US` 조회인 질문 42개는 다른 태스크가 없을 때 Basic의 동시 실행 50개
안에 들어갑니다.

인증 오류는 다른 요청과 같습니다. [오류](/ko/concepts/errors.md)를 참고하세요.

### 실패한 질문과 조회

* 실패한 질문은 `via[]`에 `status: "FAILED"`와 `error`가 있고, 과금하지 않습니다. 질문이 모두 실패한 엔진은
  `status: "FAILED"`, `found: null`이며 `summary.failed`에 들어갑니다.
* `GET /v1/product-lookup/{id}`는 계정에 그 id의 조회가 없으면 `404 RESOURCE_NOT_FOUND`를 반환합니다. 태스크를
  읽을 수 있는 기간이 지난 조회도 같습니다.

## 다음 단계

> **[GEO 모니터링](/ko/monitors.md)**
>
> 쇼핑 질문을 여러 AI 엔진에서 정해진 주기로 추적합니다.

> **[Prompt Research](/ko/research/prompt-research.md)**
>
> 한 분야에서 사람들이 묻는 쇼핑 질문을 찾습니다.


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