> ## 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 : voir comment les moteurs d'achat IA montrent un produit

> Interrogez ChatGPT, Google AI Overviews, AI Mode, Copilot et Naver AI Tab sur un produit et voyez, moteur par moteur, si la réponse l'a montré, quelles offres de marchands elle a utilisées et quelles pages elle a citées.

Product Lookup vous montre un produit tel que les moteurs d'achat IA le présentent aux acheteurs. Envoyez un nom de produit et un marché, et querying.ai interroge chaque moteur à son sujet. Pour chaque moteur, vous savez si la réponse a montré le produit, quelles offres de marchands elle a affichées (marchand, catalogue, prix, stock, note et nombre d'avis) et quelles pages elle cite. Ajoutez jusqu'à cinq concurrents pour les comparer moteur par moteur, et jusqu'à trois prompts d'achat, comme `best moisturizing eye cream`, pour voir lesquels de ces produits chaque moteur montre à un acheteur.

Une recherche vous indique par exemple :

* si ChatGPT, Google AI Overviews, AI Mode ou Copilot montrent le produit quand on les interroge à son sujet ;
* par quels marchands et quelles fiches de catalogue chaque moteur le montre, à quel prix, avec quelle note et combien d'avis ;
* ce que le modèle qui répond dans ChatGPT a lu sur le produit ;
* comment le produit se situe face à ses concurrents sur chaque moteur ;
* lesquels de ces produits chaque moteur montre pour une recherche d'achat.

## Soumettre une recherche

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

La recherche est découpée en questions : une question est posée à un moteur sur un produit ou un prompt. Chaque question est mise en file comme une tâche ordinaire, et la réponse de l'API les liste. Elle est réduite ici à trois des 23 questions :

```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` est votre `idempotencyKey`, ou un UUID choisi par le serveur si vous n'en envoyez pas. C'est avec lui que vous lisez la recherche.
* Chaque entrée de `asks[]` porte son `role` (`product`, `competitor` ou `prompt`), le texte posé dans `prompt` ou `query`, et sa `task`. Une question refusée porte `success: false` et une `error` à la place de `task`. Voir [Erreurs](#erreurs).
* `credits.creditsToCharge` additionne les prix des questions renvoyées, bloqués sur votre solde jusqu'à la fin de chaque question. `creditsCharged` est ce qui leur a déjà été prélevé.

Lisez la recherche avec `GET /v1/product-lookup/{id}` jusqu'à ce que `lookup.status` vaille `COMPLETED`. Cette recherche a pris environ deux minutes ; une recherche se termine quand son moteur le plus lent répond. Avec `webhook.url`, la tâche de chaque question vous est envoyée quand elle se termine, avec la clé de la question dans `task.idempotencyKey`, qui commence par l'id de la recherche. Aucun webhook ne couvre la recherche entière : à chaque livraison, lisez la recherche et vérifiez `lookup.status`. Les schémas sont dans la référence de l'API : [Product Lookup](/fr/api-reference/product-lookup.md) et [Lire un Product Lookup](/fr/api-reference/get-product-lookup.md).

## Champs de la requête

| Champ | Obligatoire | Description |
| - | - | - |
| `product` | Oui | Le nom du produit tel que les acheteurs l'écrivent, de 1 à 200 caractères, comme `belif Moisturizing Eye Bomb`. Une URL de page produit ou un GTIN renvoie `400 VALIDATION_ERROR`. |
| `country` | Oui | `US` (États-Unis) ou `KR` (Corée du Sud), sans tenir compte de la casse. Toute autre valeur renvoie `422 REGION_UNSUPPORTED`. |
| `competitors` | Non | Jusqu'à 5 noms d'autres produits, avec les règles de `product`. Chacun reçoit les questions posées pour le produit. Un nom identique à celui du produit, ou présent deux fois, renvoie `400`. Les noms qui ne diffèrent que par la casse, la ponctuation ou les espaces comptent comme identiques. |
| `prompts` | Non | Jusqu'à 3 prompts d'achat de 1 à 300 caractères, comme `best moisturizing eye cream`. Chacun est posé une fois à chaque moteur, tel quel. |
| `engines` | Non | Les moteurs à interroger : `CHATGPT`, `GOOGLE`, `AIMODE`, `BING_COPILOT`, `GEMINI`, et `NAVER_AI_TAB` en `KR` uniquement. Par défaut, les moteurs du marché indiqués plus bas. |
| `idempotencyKey` | Non | Nomme la recherche : de 1 à 200 caractères, sans espace au début ni à la fin. Voir [Renvoyer une recherche](#renvoyer-une-recherche). |
| `priority` | Non | Entier de `1` à `10`, `1` par défaut, appliqué à chaque question. Les valeurs hors plage sont ramenées à la borne la plus proche. Elle ne garantit pas l'ordre d'exécution. |
| `webhook.url` | Non | Reçoit la tâche de chaque question quand elle se termine. Voir [Webhooks](/fr/concepts/webhooks.md). |

## Moteurs et questions

Le produit et chaque concurrent reçoivent les mêmes questions :

| Moteur | `US` | `KR` |
| - | - | - |
| `CHATGPT` | `Buy {product}` et `Find the best price for {product}` | `{product} 구매` et `{product} 최저가` |
| `GOOGLE` (AI Overviews) | Le nom du produit | Le nom du produit, sur demande |
| `AIMODE` (AI Mode) | Le nom du produit | Le nom du produit |
| `BING_COPILOT` (Copilot) | Le nom du produit | Le nom du produit, sur demande |
| `NAVER_AI_TAB` (Naver AI Tab) | Non disponible | Le nom du produit |
| `GEMINI` | Le nom du produit, sur demande | Le nom du produit, sur demande |

« Sur demande » signifie que le moteur n'est interrogé que si vous l'indiquez dans `engines`. Sans `engines`, une recherche `US` interroge ChatGPT, AI Overviews, AI Mode et Copilot, soit 5 questions par produit. Une recherche `KR` interroge Naver AI Tab, ChatGPT et AI Mode, soit 4 questions par produit. Un prompt d'achat est posé une fois à chaque moteur : 4 questions avec les moteurs par défaut de `US`, 3 avec ceux de `KR`. La recherche ci-dessus a posé 3 × 5 + 2 × 4 = 23 questions.

ChatGPT reçoit deux questions, car une seule montre une fiche produit pour environ la moitié des produits, et la même question répétée tombe souvent sur une autre moitié. Les autres moteurs par défaut sont ceux qui ont montré des produits lors d'un test sur 50 produits le 2026-10-20 :

| Moteur | `US` | `KR` |
| - | - | - |
| ChatGPT, les deux questions, cartes widget comprises | 24 recherches sur 24 | 20 recherches sur 20 |
| Copilot | 25 sur 25 | 0 sur 25 |
| Google AI Overviews | 23 sur 25 | 1 sur 25 |
| Google AI Mode | 23 sur 25 | 13 sur 25 |
| Naver AI Tab | – | 25 sur 25 |

La ligne ChatGPT provient de 12 produits `US` et 10 produits `KR`, recherchés deux fois chacun. Gemini n'a montré aucune fiche produit en 115 questions sur les deux marchés.

## Lire la recherche

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

Le résultat comporte cinq parties :

* `lookup` : ce qui a été demandé, son `status` et les `credits` prélevés jusqu'ici.
* `summary` et `engines[]` : les réponses sur le produit, tous moteurs confondus puis moteur par moteur.
* `competitors[]` : les mêmes `summary` et `engines[]` pour chaque concurrent.
* `comparison[]` : le produit et ses concurrents côte à côte, moteur par moteur.
* `prompts[]` : ce que chaque moteur a répondu à chaque prompt d'achat.

`lookup.status` vaut `QUEUED` tant qu'aucune question n'a commencé et `PROCESSING` tant qu'une question n'est pas terminée. Il passe à `COMPLETED` quand toutes les questions sont terminées et qu'au moins une a abouti, et à `FAILED` quand toutes ont échoué. Les entrées se remplissent au fil des questions, vous pouvez donc lire une recherche avant qu'elle soit terminée.

Voici `lookup`, `summary` et `engines[]` de la recherche ci-dessus, réduits à deux des quatre moteurs et à quelques entrées par liste :

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

Les quatre moteurs ont montré le produit. ChatGPT a montré une fiche issue du flux produits d'Ulta Beauty, et son modèle qui répond y a lu une note de 4,5 pour 105 avis. ChatGPT a aussi écrit des cartes widget pour trois boutiques, dont Amazon. AI Mode a montré l'offre d'un marchand et une version en stick marquée `variant`, et a placé le gel contour des yeux de la marque dans `otherListings`.

### `summary`

| Champ | Description |
| - | - |
| `foundIn`, `notFoundIn` | Les moteurs dont les réponses ont montré le produit, et ceux dont les questions se sont terminées sans le montrer. |
| `pending`, `failed` | Les moteurs dont des questions sont encore en cours, et ceux dont toutes les questions ont échoué. |
| `merchants[]` | Chaque marchand des offres du produit, avec les `engines` qui l'ont montré et sa fourchette de `price` à l'unité sur ces moteurs, ceux présents sur le plus de moteurs en premier. |
| `priceRange` | Les prix à l'unité sur tous les moteurs, dans la devise du marché : USD pour `US`, KRW pour `KR`. Les offres d'un autre conditionnement ou format (`match.variant`) sont exclues. |
| `citedDomains[]` | Chaque site cité par les réponses, avec les `engines` qui le citent, ceux cités par le plus de moteurs en premier. |
| `credits` | Les crédits prélevés jusqu'ici pour les questions du produit. `lookup.credits` couvre toute la recherche. |

### `engines[]`

Une entrée par moteur interrogé :

| Champ | Description |
| - | - |
| `status` | L'ensemble des questions du moteur : `QUEUED`, `PROCESSING`, `COMPLETED` quand toutes sont terminées et qu'une a abouti, ou `FAILED` quand toutes ont échoué. |
| `found` | `true` quand une réponse a montré une offre du produit, issue d'une fiche de catalogue ou d'une carte widget de ChatGPT. `false` quand toutes les questions se sont terminées sans en montrer. `null` tant que des questions sont en cours sans que rien n'ait été trouvé, et quand toutes les questions ont échoué. |
| `via[]` | Les questions du moteur dans l'ordre, chacune avec le texte posé, son `taskId`, son `status` et ses `credits`, ainsi que l'`error` d'une question en échec. |
| `listings[]` | Les offres jugées être le produit, ou un autre conditionnement ou format du produit. Une offre montrée par deux questions n'apparaît qu'une fois. |
| `otherListings[]` | Les autres produits montrés par les réponses. Une version du produit renommée ou traduite peut s'y retrouver. |
| `citedPages[]` | Les pages citées par les réponses, chacune avec `url`, `domain` (l'hôte sans `www.` ni `m.`), `title` et `ask`. Pour ChatGPT, ce sont les sources que cite sa réponse. |

### Champs d'une offre

Une offre est la fiche du produit chez un marchand, telle que le moteur la détient. Elle ne porte que les champs fournis par le moteur.

| Champ | Description |
| - | - |
| `position` | Rang dans la réponse, à partir de 1. |
| `ask` | La question du moteur qui l'a montrée, à partir de 1, dans l'ordre de `via[]`. |
| `title` | Le nom du produit sur la fiche. Sur une carte widget de ChatGPT, le titre de la carte, qui peut être le nom de la boutique. |
| `merchant` | Qui le vend. |
| `source` | D'où vient l'offre. Voir le tableau suivant. |
| `url` | La page du marchand quand le moteur en donne le lien, sinon la page produit du moteur lui-même. |
| `price`, `oldPrice` | `value`, `currency` et `raw` tel qu'affiché. `currency` est un code ISO 4217 quand le symbole n'est pas ambigu sur le marché. `oldPrice` est le prix avant une remise affichée par le moteur. |
| `available` | Si le produit est en stock. ChatGPT uniquement. |
| `rating`, `reviewCount` | La note et le nombre d'avis de la fiche. |
| `modelSees` | ChatGPT uniquement : ce que ChatGPT a transmis à son modèle qui répond au sujet de la fiche, à savoir `title`, `description`, `rating`, `reviewCount`, `brand` et `productPage`. La note et le nombre d'avis d'une fiche issue du flux d'un marchand ne se trouvent qu'ici. |
| `image`, `description`, `brand` | Tels que le moteur les affiche. |
| `reviews` | Le `summary`, les `pros` et les `cons` des avis affichés par le moteur. |
| `ids` | Les identifiants de catalogue qui relient les fiches d'un même produit, comme `chatgptProductId` et `feedId` sur ChatGPT, `googleCatalogId`, `googleProductGroupId` et `googleProductDocId` sur les moteurs Google, `bingProductId` et `bingGroupId` sur Copilot, et `naverProductId` sur Naver AI Tab. Aucun moteur ne renvoie de GTIN. |
| `pictured` | Sur une carte widget de ChatGPT : ce que montre l'image à côté de la carte, d'après la requête d'image écrite par la réponse. |
| `match` | Pourquoi l'offre compte comme le produit. `score` est la part des mots du nom du produit présents dans l'offre, de 0 à 1. `missing` liste les mots absents, `variant` signale un autre conditionnement ou format (coffret, mini, 1+1, stick) et `accessory` une pièce plutôt que le produit, comme un filtre de rechange. |

`source` indique de quel catalogue vient une offre :

| `source` | Moteur | Ce que c'est |
| - | - | - |
| `shopify` | ChatGPT | La fiche d'une boutique Shopify dans le catalogue produits de ChatGPT |
| `merchant_feed` | ChatGPT | Une fiche issue du flux produits qu'un marchand envoie à ChatGPT |
| `google_shopping` | ChatGPT, AI Overviews, AI Mode, Gemini | Une fiche Google Shopping |
| `chatgpt_catalog` | ChatGPT | Une fiche du catalogue de ChatGPT qui n'indique pas sa provenance |
| `chatgpt_widget` | ChatGPT | Une boutique et un prix que ChatGPT a écrits dans une carte widget, sans fiche derrière |
| `microsoft_shopping` | Copilot | Une offre Microsoft Shopping |
| `naver_shopping` | Naver AI Tab | Une offre Naver Shopping |

### Cartes widget de ChatGPT

ChatGPT répond souvent à une recherche d'achat par des cartes qui indiquent chacune une boutique et un prix lus sur la page de la boutique, sans fiche de catalogue derrière. Product Lookup lit chaque carte comme une offre `chatgpt_widget`, après les fiches de la réponse, et la compte pour `found`.

* `merchant` est la boutique nommée par la carte, ou le domaine de son lien d'achat. `description` est la ligne de description de la carte.
* Une carte n'a ni `rating`, ni `reviewCount`, ni `available`, ni `ids`, ni `modelSees`. Avec une fourchette de prix comme `$40–$62`, `price` est absent.
* Une carte qui n'a ni lien d'achat ni ligne vendeur n'est pas lue.
* Une carte qui reprend la boutique et le prix d'une fiche ou d'une carte précédente du produit est écartée. Deux boutiques sont considérées comme identiques quand leurs noms ou les sites liés correspondent, ou que l'un commence par l'autre, comme Ulta, Ulta Beauty et ulta.com.

Pour ne lire que les fiches de catalogue, laissez de côté les offres dont la `source` vaut `chatgpt_widget`.

## Comparer avec les concurrents

Une question sur un produit montre rarement le produit d'une autre marque ; aucune ne l'a fait lors du test sur 50 produits. C'est donc vous qui nommez les concurrents, et chacun reçoit les questions du produit. Chaque entrée de `competitors[]` contient le `product`, le `summary` et les `engines[]` du concurrent, à lire comme ceux du produit.

`comparison[]` aligne le produit et ses concurrents, une ligne par produit et une entrée par moteur. D'après la recherche ci-dessus, réduite à Copilot, avec ChatGPT en plus pour le produit :

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

| Champ | Description |
| - | - |
| `role` | `product` ou `competitor`. |
| `found` | Comme dans `engines[]`. |
| `listings` | Le nombre d'offres jugées être le produit, cartes widget de ChatGPT comprises. |
| `merchants` | Le nombre de marchands parmi ces offres. |
| `mostReviewed` | L'offre qui a le plus d'avis : son `reviewCount`, sa `rating` et son `merchant`. Pour ChatGPT, le nombre transmis à son modèle qui répond dans `modelSees`. Copilot attache le nombre d'avis d'un produit à l'offre de chaque marchand, donc `merchant` est la première offre qui le porte. |
| `priceRange` | Les prix à l'unité sur ce moteur. |
| `prompts` | Seulement quand la recherche a des prompts d'achat : `answered` indique à combien d'entre eux le moteur a répondu, et `appeared` combien de ces réponses ont montré ou nommé le produit. |

Les trois produits ont été trouvés sur les quatre moteurs. Sur Copilot, l'offre du produit qui a le plus d'avis en compte 2 942, contre 85 773 et 117 193 pour les deux concurrents. Sur les huit réponses aux prompts d'achat, CeraVe Eye Repair Cream est apparu dans cinq, le produit et Clinique All About Eyes dans deux chacun.

## Prompts d'achat

Chaque entrée de `prompts[]` contient le `prompt` et une entrée par moteur dans `engines[]` :

| Champ | Description |
| - | - |
| `shown` | Les produits de la recherche, le produit et ses concurrents, que la réponse a montrés sous forme de fiche ou de carte widget, dans l'ordre d'affichage. |
| `named` | Les produits de la recherche que le texte de la réponse nomme, dans l'ordre où ils sont nommés. |
| `listings[]` | Chaque fiche produit et chaque carte widget de la réponse. Celles qui correspondent à un produit de la recherche portent `product` et `match`. |
| `via[]`, `citedPages[]` | Comme dans `engines[]`. |

La réponse à un prompt d'achat montre des produits de nombreuses marques. Une fiche ne compte donc comme l'un des produits de la recherche que si elle contient la marque, c'est-à-dire le premier mot du nom du produit. Un nom dans le texte compte de la même façon qu'un [moniteur GEO](/fr/monitors.md) compte une mention de marque, avec le nom complet du produit comme terme.

D'après la recherche ci-dessus, AI Overviews et Copilot répondant à `best moisturizing eye cream`, avec les offres réduites aux produits de la recherche :

```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 a nommé le produit dans son texte, mais n'a montré que des fiches des deux concurrents. Copilot a montré le produit chez trois marchands. La correspondance repose sur les noms : une version dont le nom ajoute un mot, comme `Clinique All About Eyes Rich`, compte comme le produit concerné.

## Renvoyer une recherche

Chaque question a sa propre clé, construite à partir de l'id de la recherche :

* Les questions du produit : `<id>:<engine>:<ask>`, comme `eye-bomb-us:CHATGPT:buy`. Les questions de ChatGPT sont `buy` et `price`, celle des autres moteurs est `name`.
* Les questions du n-ième concurrent ajoutent `:c<n>`, comme `eye-bomb-us:CHATGPT:buy:c1`.
* Les questions du n-ième prompt : `<id>:<engine>:p<n>`, comme `eye-bomb-us:AIMODE:p1`.

Si vous renvoyez une recherche avec le même `idempotencyKey`, l'API rend les questions existantes et n'ajoute que celles qui manquent, et seules les questions ajoutées vous sont facturées. Servez-vous-en pour terminer une recherche dont des questions ont été refusées pour manque de crédits ou limite de concurrence, ou pour ajouter un concurrent ou un prompt en fin de liste. Un concurrent ou un prompt que vous omettez reste dans la recherche.

Un renvoi qui change le produit ou le pays, ou qui place un autre concurrent ou un autre prompt à une position déjà occupée, renvoie `409 RESOURCE_ALREADY_EXISTS` et n'écrit rien. Une question qui a échoué est rendue telle quelle par un renvoi. Pour obtenir de nouvelles réponses des moteurs, envoyez la recherche avec un nouvel `idempotencyKey`.

## Prix

Une recherche coûte 10 crédits par produit, le produit comme chaque concurrent, et 5 crédits par prompt d'achat, quels que soient les moteurs interrogés.

* La recherche ci-dessus coûte 3 × 10 + 2 × 5 = 40 crédits. La plus grande recherche, un produit avec 5 concurrents et 3 prompts, coûte 75 crédits.
* Les crédits d'un produit ou d'un prompt sont répartis entre ses questions. Avec les moteurs par défaut de `US`, une question de produit coûte 2 crédits et une question de prompt 1,25. Avec ceux de `KR`, une question de produit coûte 2,5 crédits et les trois questions d'un prompt 1,67, 1,67 et 1,66. Interroger moins de moteurs ne baisse pas le prix : avec ChatGPT seul, chacune des deux questions d'un produit coûte 5 crédits.
* Chaque question est bloquée à la soumission et prélevée quand elle aboutit, comme toute tâche. Une question qui échoue n'est pas facturée.
* Au prix des plans, un produit coûte 0,025 \$ sur Basic et 0,010 \$ sur Max.

Consultez [Crédits et limites](/fr/concepts/credits-and-limits.md) pour les blocages et les plans.

## Bien lire les résultats

* **Une recherche est un instantané.** Chaque moteur répond à une ou deux questions. Avant d'agir sur une seule différence, relancez la recherche avec un nouvel `idempotencyKey`.
* **Les fiches gardent leurs valeurs ; c'est la sélection qui change.** Sur quatre exécutions d'une même recherche, la même fiche marchand a gardé son prix, sa note et son nombre d'avis pour 307 valeurs sur 316. Ce qui change d'une exécution à l'autre, ce sont les fiches qu'une réponse montre : `found` (surtout sur ChatGPT), les marchands, `mostReviewed`, `priceRange` et les `shown` et `named` des prompts peuvent donc différer.
* **Quelques minutes d'écart changent autant que quelques heures.** Les réponses de ChatGPT, d'AI Mode et de Copilot ont autant différé à trois minutes d'écart qu'à onze heures. Réinterrogé dans les secondes qui suivent, AI Overviews peut renvoyer la même réponse : une répétition rapide n'y donne pas un nouvel échantillon.
* **Les totaux sont plus stables que les réponses isolées.** Sur les quatre exécutions, les réponses aux prompts d'achat ont changé une à une, mais les produits apparus dans le plus de réponses sont arrivés en tête à chaque fois. Pour suivre des prompts dans le temps, utilisez un [moniteur GEO](/fr/monitors.md).
* **`found: false` décrit ces réponses.** Cela signifie que les questions de cette exécution n'ont pas montré le produit. Cela ne signifie pas que le catalogue du moteur ne l'a pas.
* **La correspondance repose sur les noms.** Aucun moteur ne renvoie de GTIN. Un produit renommé ou traduit peut se retrouver dans `otherListings`, et une version que son nom ne distingue pas peut compter comme le produit. Vérifiez `match` quand une offre semble incorrecte.

## Limites

* L'entrée est un nom de produit. Les URL de pages produit et les GTIN ne sont pas pris en charge.
* Les marchés sont `US` et `KR`.
* Une recherche accepte jusqu'à 5 concurrents et 3 prompts d'achat. Avec les moteurs par défaut de `US`, la plus grande recherche pose 42 questions.
* Les concurrents sont ceux que vous nommez. Une recherche ne les trouve pas pour vous ; les prompts d'achat montrent quels produits un moteur met devant les acheteurs.
* Les fiches et les cartes widget de ChatGPT sont lues. Les boutiques et les prix qu'il écrit dans le texte ou les tableaux de la réponse ne le sont pas.
* Chaque réponse apporte au plus 60 offres et 20 pages citées.
* Une recherche peut être lue tant que les tâches de ses questions peuvent l'être, jusqu'à 24 heures après leur fin. Voir [Tâches asynchrones](/fr/concepts/async-tasks.md#conservation).

## Erreurs

### Rejets à la soumission

| Statut | Code | Cause |
| - | - | - |
| `400` | `VALIDATION_ERROR` | Le corps n'est pas un JSON valide, ou un champ enfreint une règle ci-dessus : `product` ou `country` manquant, une URL ou un GTIN comme nom, trop de `competitors` ou de `prompts` ou des doublons, un moteur inconnu ou non proposé sur le marché, ou un `idempotencyKey` invalide. `details` indique le champ. |
| `422` | `REGION_UNSUPPORTED` | `country` n'est ni `US` ni `KR`. |
| `409` | `RESOURCE_ALREADY_EXISTS` | L'`idempotencyKey` désigne une recherche portant sur un autre produit ou un autre pays, ou avec un autre concurrent ou prompt à la même position. Rien n'a été écrit. |

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

### Questions refusées

Chaque question est admise comme une tâche isolée ; elle peut donc être refusée à cause de votre solde (`402 INSUFFICIENT_CREDITS`), de la concurrence de votre plan (`429 PLAN_CONCURRENCY_LIMIT`), de la limite quotidienne de crédits d'une clé (`429 KEY_DAILY_CREDIT_LIMIT`) ou d'une clé limitée à d'autres moteurs. Une question refusée reste dans `asks[]` avec `success: false` et son `error`, et les autres questions continuent.

Les questions sont admises une par une : la première question de chaque moteur sur chaque produit, et chaque prompt, passent avant toute deuxième question. Quand votre plan n'a de place que pour une partie des questions, celles qui sont admises couvrent donc autant de moteurs et de produits que possible. Si aucune des premières questions du produit n'est admise, aucune autre question n'est posée, et la réponse de l'API est le premier refus avec son statut, comme `402 INSUFFICIENT_CREDITS`. Avec les 2 tâches simultanées du plan Free, une recherche `US` admet les premières questions du produit à ChatGPT et à AI Overviews ; renvoyez-la quand elles sont terminées pour ajouter le reste. La plus grande recherche `US`, 42 questions, tient dans les 50 tâches simultanées de Basic quand rien d'autre n'est en file.

Les erreurs d'authentification sont les mêmes que pour toute requête. Voir [Erreurs](/fr/concepts/errors.md).

### Questions en échec et lectures

* Une question qui échoue a `status: "FAILED"` et une `error` dans `via[]`, et n'est pas facturée. Un moteur dont toutes les questions ont échoué a `status: "FAILED"` et `found: null`, et figure dans `summary.failed`.
* `GET /v1/product-lookup/{id}` renvoie `404 RESOURCE_NOT_FOUND` pour un id sans recherche sur votre compte, y compris une recherche dont les tâches ont dépassé la période de lecture.

## Étapes suivantes

> **[Moniteurs GEO](/fr/monitors.md)**
>
> Suivez des prompts d'achat sur les moteurs IA selon un calendrier.

> **[Prompt Research](/fr/research/prompt-research.md)**
>
> Trouvez les questions d'achat que les gens posent sur une catégorie.


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