> ## 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 购物引擎询问一个商品、你指定的竞品以及购物提示词。 ## OpenAPI ````yaml POST /v1/product-lookup openapi: 3.1.0 info: title: querying.ai description: >- One API for every AI answer engine. Every task is asynchronous: submit, then collect the result via webhook or polling. version: 1.0.0 servers: - url: https://api.querying.ai description: Production security: - bearerAuth: [] paths: /v1/product-lookup: post: tags: - Research summary: Look up a product on AI shopping engines description: >- Asks the AI shopping engines of one market (US or KR) about a product by name, and about up to 5 competitors and 3 shopper prompts you name. Each ask is an ordinary task, so polling, webhooks, credits and plan concurrency are those of single tasks. A product's asks have the key `::`, a competitor's add `:c`, and a prompt's are `::p`. Read the lookup with GET /v1/product-lookup/{id}. Asks are admitted one at a time: every engine's first ask about each product, and each prompt, before any second ask. A refused ask stays in asks[] with success false. When none of the product's first asks is admitted, nothing else is asked and the first refusal is the response. Sending the lookup again under the same idempotencyKey returns the asks that exist and admits only the missing ones. A lookup costs 10 credits per product (the product and each competitor) and 5 credits per shopper prompt, whichever engines are asked. Each ask carries its share of its product's or prompt's credits, and an ask that fails is not charged. operationId: createProductLookup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductLookupRequest' examples: lookup: summary: A product with competitors and shopper prompts value: 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 responses: '200': description: >- Asks processed. Each entry of asks[] holds its task, or the error that refused it. content: application/json: schema: $ref: '#/components/schemas/ProductLookupCreateResponse' example: 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 '400': description: >- VALIDATION_ERROR: the body is not valid JSON; product or a competitor is missing, a product page URL or a GTIN; there are more than 5 competitors or 3 prompts, or a duplicate; an engine is unknown or does not answer in the market; or idempotencyKey is not 1-200 characters without leading or trailing spaces. details names the field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: 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:22:43.000Z' '401': $ref: '#/components/responses/Unauthorized' '402': description: >- INSUFFICIENT_CREDITS: none of the product's first asks could be held, so nothing was asked. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The API key may not use the engines of the product's first asks, so nothing was asked. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- RESOURCE_ALREADY_EXISTS: the idempotencyKey names a lookup of another product or country, or one that holds a different competitor or prompt in the same position. Nothing was written. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RESOURCE_ALREADY_EXISTS message: >- lookup 'eye-bomb-us' was created for another product, competitor, prompt or country; send this lookup under a new idempotencyKey timestamp: '2026-10-20T09:22:43.000Z' '413': description: 'PAYLOAD_TOO_LARGE: the body is over 1 MiB.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'REGION_UNSUPPORTED: country is not US or KR.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: REGION_UNSUPPORTED message: >- Product lookups ask the engines of US and KR only; country='JP' is not one. details: country: JP supportedCountries: - US - KR retryable: false timestamp: '2026-10-20T09:22:43.000Z' '429': description: >- None of the product's first asks was admitted, for example PLAN_CONCURRENCY_LIMIT or KEY_DAILY_CREDIT_LIMIT. Retry after Retry-After. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- None of the product's first asks was admitted because the service is busy. Retry after Retry-After. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ProductLookupRequest: type: object required: - product - country properties: product: type: string minLength: 1 maxLength: 200 description: >- The product's name, such as belif Moisturizing Eye Bomb. A product page URL or a GTIN is a 400 VALIDATION_ERROR. country: type: string enum: - US - KR description: >- Market: US (United States) or KR (South Korea), case-insensitive. Any other value is a 422 REGION_UNSUPPORTED. competitors: type: array maxItems: 5 items: type: string minLength: 1 maxLength: 200 description: >- Other products' names, asked what the product is asked. A name that is the product's or is listed twice is a 400; names that differ only in case, punctuation or spacing are the same name. prompts: type: array maxItems: 3 items: type: string minLength: 1 maxLength: 300 description: >- Shopper prompts, such as best moisturizing eye cream. Each is asked of each engine once, as written. engines: type: array minItems: 1 maxItems: 6 uniqueItems: true items: $ref: '#/components/schemas/ProductLookupEngine' description: >- The engines to ask, case-insensitive. Default for US: CHATGPT, GOOGLE, AIMODE and BING_COPILOT. Default for KR: NAVER_AI_TAB, CHATGPT and AIMODE. NAVER_AI_TAB in a US lookup is a 400. idempotencyKey: type: string minLength: 1 maxLength: 200 description: >- Names the lookup; without it the server picks a UUID. Sending the lookup again under the same key admits only the asks that are missing. priority: type: integer minimum: 1 maximum: 10 default: 1 description: >- Set on every ask. Values outside 1-10 are clamped. It does not guarantee execution order. webhook: type: object description: >- Optional. Each ask's task is posted here when it reaches a terminal state. required: - url properties: url: type: string format: uri ProductLookupCreateResponse: type: object properties: success: type: boolean lookup: type: object properties: id: type: string description: Your idempotencyKey, or the UUID the server picked. product: type: string competitors: type: array items: type: string prompts: type: array items: type: string country: type: string enum: - US - KR engines: type: array items: $ref: '#/components/schemas/ProductLookupEngine' description: The engines asked. summary: type: object properties: total: type: integer succeeded: type: integer failed: type: integer credits: type: object description: >- creditsToCharge adds up the prices of the asks in asks[], held from your balance until each ask finishes. creditsCharged is what those asks have been charged already: 0 on a first submit, and on a resend the charges of the asks that had finished. properties: creditsToCharge: type: number creditsCharged: type: number asks: type: array items: $ref: '#/components/schemas/ProductLookupAsk' ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/ErrorDetail' ProductLookupEngine: type: string description: >- An engine a product lookup can ask. GOOGLE is Google AI Overviews and AIMODE is Google AI Mode. NAVER_AI_TAB answers in KR only. enum: - CHATGPT - GOOGLE - AIMODE - GEMINI - BING_COPILOT - NAVER_AI_TAB ProductLookupAsk: type: object required: - engine - taskType - role - success properties: engine: $ref: '#/components/schemas/ProductLookupEngine' taskType: allOf: - $ref: '#/components/schemas/ProductLookupEngine' description: The ask's task type, the same as engine. role: type: string enum: - product - competitor - prompt description: >- Whether the ask is about the product, a competitor or a shopper prompt. prompt: type: string description: The text asked, on CHATGPT, GEMINI and BING_COPILOT. query: type: string description: The text asked, on GOOGLE, AIMODE and NAVER_AI_TAB. success: type: boolean task: allOf: - $ref: '#/components/schemas/TaskMeta' description: The ask's task, when it was admitted or already existed. error: allOf: - $ref: '#/components/schemas/ErrorDetail' description: >- Why the ask was refused, such as INSUFFICIENT_CREDITS or PLAN_CONCURRENCY_LIMIT. ErrorDetail: type: object required: - code - message properties: code: type: string description: Stable, safe to branch on. See the Errors guide for the full list. message: type: string description: For humans. May change. details: description: >- Context for the error. An array of `{field, message}` on most `VALIDATION_ERROR`s; an object elsewhere (for example `{id}` on `RESOURCE_NOT_FOUND`, `retryAfterSec` on 429 and 503 codes). Omitted when there is nothing to add. oneOf: - type: array items: type: object properties: field: type: string message: type: string - type: object additionalProperties: true timestamp: type: string format: date-time TaskMeta: type: object required: - id - taskType - status - priority - createdAt properties: id: type: string format: uuid taskType: $ref: '#/components/schemas/TaskType' status: $ref: '#/components/schemas/TaskStatus' priority: type: integer createdAt: type: string format: date-time idempotencyKey: type: string description: >- Echoed back verbatim. **Omitted** — not null — when the caller supplied none. TaskType: type: string description: >- The engine to query. `NAVER` is a deprecated alias for `NAVER_AI_BRIEF`. GOOGLE_AIO and GOOGLE_AIMODE are the unified names for GOOGLE and AIMODE; both spellings are accepted and responses echo the canonical GOOGLE / AIMODE. `NAVER_AI_MODE` is accepted as an earlier spelling of `NAVER_AI_TAB`. `GOOGLE_SERP` returns the Google results page without the AI Overview; `payload.page` selects pages 1-10. `NAVER_SERP` returns Naver's web results, 15 per page (`payload.page` 1-10), and with `payload.action` `page` reads one naver.com page by `payload.url`. `REDDIT` searches Reddit posts by `query` (optionally within one `subreddit`), reads one post with its first page of comments by `url`, or lists posts with `action` `feed` or `user_posts`. `WEB_SCRAPE` reads one web page by `payload.url` and returns its main content as Markdown with its images. `WEB_MAP` lists a site's addresses from its start page links and sitemaps. `WEB_CRAWL` reads a site's pages under a start address, each as WEB_SCRAPE reads it, at 1 credit per page returned. `KEYWORD_VOLUME` returns the monthly search volume of `payload.keywords` (1-100) in `payload.country`: Naver for KR and Google for 216 other countries. `META_AI` returns the meta.ai chat answer with its cited sources, search queries and the products it shows (`shoppingCards`, `inlineProducts`); a prompt Meta refuses completes with an empty text and a `notice` quoting Meta. `QWEN` returns the answer of Qwen's China web chat (qianwen.com) with its web search, sources and search queries; `payload.country` sets the exit and the answer locale. `DOUBAO` returns the answer of Doubao's China web chat (doubao.com) with its web search, sources and search queries; it always asks from mainland China, whatever `payload.country` is. `BING` and `BING_COPILOT_SEARCH` are accepted as earlier spellings of `BING_SEARCH`, and `COPILOT` as the earlier spelling of `BING_COPILOT`; responses echo the new names. Private engines (for example CLAUDE) are rejected with 403 ENGINE_PRIVATE. CITATION_ANALYSIS, PROMPT_RESEARCH and GEO_SCORE tasks are created through their own endpoints (POST /v1/citation-analysis, POST /v1/prompt-research, POST /v1/geo-score) and are rejected here with 400 USE_DEDICATED_ENDPOINT; they appear in this list because their tasks report them. GEO_AUDIT, SOURCE_INFLUENCE and CITATION_ATTRIBUTION are accepted as earlier names of CITATION_ANALYSIS; responses echo CITATION_ANALYSIS. enum: - CHATGPT - PERPLEXITY - GEMINI - AIMODE - GOOGLE_AIMODE - GOOGLE - GOOGLE_AIO - GOOGLE_SERP - NAVER_AI_BRIEF - NAVER_AI_TAB - NAVER_AI_MODE - NAVER - NAVER_SERP - COMMERCE_SERP - COMMERCE_PRODUCT - BING_SEARCH - BING - BING_COPILOT_SEARCH - BING_COPILOT - COPILOT - META_AI - QWEN - DOUBAO - REDDIT - WEB_SCRAPE - WEB_MAP - WEB_CRAWL - KEYWORD_VOLUME - CITATION_ANALYSIS - GEO_AUDIT - SOURCE_INFLUENCE - CITATION_ATTRIBUTION - PROMPT_RESEARCH - GEO_SCORE TaskStatus: type: string description: >- `PROCESSING` means a worker holds the task. `COMPLETED` and `FAILED` are terminal. enum: - QUEUED - PROCESSING - COMPLETED - FAILED responses: Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: MISSING_API_KEY message: Missing or invalid API key timestamp: '2026-07-09T04:12:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key, sent as `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.