> ## 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. # 创建批次 > 以一个批次提交最多 10,000 个任务并获取批次 ID。 ## OpenAPI ````yaml POST /v1/batches 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/batches: post: tags: - Tasks summary: Create a batch description: >- Submit up to 10,000 tasks as one batch and receive a batch id. Every item is checked first: one invalid item returns `400` with the failing items' indexes and nothing is stored. The batch keeps its items and turns them into tasks as your plan's active-task limit and each engine's queue have room, so a batch larger than your limit runs through without retries on your side. Accounts share engine room turn by turn, so a large batch and a small one from another account move together. Follow progress with `GET /v1/batches/{id}` and read results with `GET /v1/batches/{id}/items`. With `webhook.url`, each task posts its result there as a single task does, and the batch posts `{"event":"batch.completed","batch":{...}}` once when it completes, signed with the same `querying-webhook-*` headers (`querying-webhook-id` is `batch_`). `POST /v1/async/task/batch` (500 tasks, created in the request) remains available. operationId: createBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchRequest' example: idempotencyKey: daily-2026-10-09 webhook: url: https://example.com/hooks/querying metadata: run: daily items: - customId: shoes-chatgpt-us taskType: CHATGPT payload: prompt: best running shoes 2026 country: US - customId: shoes-gemini-us taskType: GEMINI payload: prompt: best running shoes 2026 country: US responses: '200': description: >- A batch with this `idempotencyKey` already exists; it is returned unchanged. content: application/json: schema: $ref: '#/components/schemas/BatchResponse' '202': description: Batch stored. The first items are already queued. content: application/json: schema: $ref: '#/components/schemas/BatchResponse' example: success: true batch: id: 3f6b2a10-0000-0000-0000-000000000000 status: OPEN total: 10000 counts: pending: 9520 queued: 480 processing: 0 completed: 0 failed: 0 rejected: 0 createdAt: '2026-10-09T09:00:00.000Z' completedAt: null idempotencyKey: daily-2026-10-09 webhook: url: https://example.com/hooks/querying metadata: run: daily '400': description: >- Invalid body or items. `details.items` lists up to 50 failing items with their index, code and message; `details.invalidItems` counts all of them. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: 1 of 10000 items are invalid; the batch was not stored details: invalidItems: 1 items: - index: 17 code: VALIDATION_ERROR message: Request validation failed details: - field: payload.prompt message: 'Invalid input: expected string, received undefined' timestamp: '2026-10-09T09:00:00.000Z' '401': $ref: '#/components/responses/Unauthorized' '413': description: Body exceeds 32 MiB. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: PAYLOAD_TOO_LARGE message: batch body exceeds 33554432 bytes timestamp: '2026-10-09T09:00:00.000Z' components: schemas: BatchRequest: type: object required: - items properties: items: type: array minItems: 1 maxItems: 10000 items: $ref: '#/components/schemas/BatchItemRequest' webhook: type: object required: - url properties: url: type: string format: uri description: >- Each item's task posts its result here, and the batch posts one `batch.completed` event when it finishes. metadata: type: object additionalProperties: true description: Up to 8 KB of JSON, returned with the batch. idempotencyKey: type: string maxLength: 256 description: Sending the same key again returns the first batch. BatchResponse: type: object required: - success - batch properties: success: type: boolean const: true batch: $ref: '#/components/schemas/Batch' ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/ErrorDetail' BatchItemRequest: type: object required: - taskType - payload description: >- One task of a batch: the fields of a single task request, plus an optional `customId`. `webhook` is set once on the batch. properties: customId: type: string maxLength: 128 description: Your own id for the item, returned with its result. taskType: $ref: '#/components/schemas/TaskType' payload: $ref: '#/components/schemas/Payload' priority: type: integer minimum: 1 maximum: 10 default: 1 idempotencyKey: type: string description: >- Unique inside the batch. Omitted, the item's task is created with a key derived from the batch id and its index, so it is created once. allOf: - if: properties: taskType: const: COMMERCE_SERP required: - taskType then: properties: payload: $ref: '#/components/schemas/CommerceSerpPayload' - if: properties: taskType: const: COMMERCE_PRODUCT required: - taskType then: properties: payload: $ref: '#/components/schemas/CommerceProductPayload' Batch: type: object required: - id - status - total - counts - createdAt - completedAt - metadata properties: id: type: string format: uuid status: type: string enum: - OPEN - COMPLETED description: '`COMPLETED` once no item is pending, queued or processing.' total: type: integer counts: $ref: '#/components/schemas/BatchCounts' createdAt: type: string format: date-time completedAt: type: - string - 'null' format: date-time idempotencyKey: type: string webhook: type: object properties: url: type: string metadata: type: - object - 'null' 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 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 Payload: type: object description: >- Engine payloads share this envelope. COMMERCE_SERP requires site and query (see CommerceSerpPayload). COMMERCE_PRODUCT requires url, a product page on a supported storefront (see CommerceProductPayload). Other scraping engines require prompt or query; WEB_SCRAPE, WEB_MAP and WEB_CRAWL require url; KEYWORD_VOLUME requires keywords and country. CITATION_ANALYSIS has its own endpoint (POST /v1/citation-analysis, with answer and citations at the top level; GEO_AUDIT, SOURCE_INFLUENCE and CITATION_ATTRIBUTION are accepted aliases) and is rejected here with 400 USE_DEDICATED_ENDPOINT. properties: prompt: type: string description: The question, for LLM engines. query: type: string description: >- The search term, for GOOGLE, AIMODE, GOOGLE_SERP, BING_SEARCH, REDDIT, COMMERCE_SERP and NAVER_* engines. BING_SEARCH reads `prompt` first and falls back to `query`, and rejects text over 4,000 characters with 422 VALIDATION_ERROR. country: type: string description: >- ISO 3166-1 alpha-2 country code, case-insensitive. Omitted, empty or null means `US` (`KR` for NAVER_* engines). A value that is not an officially assigned code, such as `UK` (use `GB`), is rejected with 400 VALIDATION_ERROR, and a country this engine cannot serve is rejected at submit time with 422. example: US location: type: object additionalProperties: false required: - latitude - longitude properties: latitude: type: number minimum: -90 maximum: 90 longitude: type: number minimum: -180 maximum: 180 description: >- CHATGPT, GEMINI, GOOGLE, AIMODE and GOOGLE_SERP. The point to ask from, in decimal degrees (WGS84). The engine answers as a user standing there, so local recommendations come from that neighborhood. Send a point inside `country`: `country` sets the market and this point sets the device location. The response echoes it as `location`. example: latitude: 37.4979 longitude: 127.0276 followUps: type: array minItems: 1 maxItems: 4 description: >- CHATGPT only. Questions asked after the first answer in the same conversation, in order. Each answer costs 1 credit. The result lists the answers in followUps and, when a select cannot be pressed, where and why the turns stopped in followUpsStopped. items: oneOf: - type: object additionalProperties: false required: - prompt properties: prompt: type: string minLength: 1 maxLength: 100000 description: A question of your own. - type: object additionalProperties: false required: - select properties: select: $ref: '#/components/schemas/FollowUpSelect' description: Press a follow-up form's button in the previous answer. continueFrom: type: string format: uuid description: >- CHATGPT only. The id of a completed CHATGPT task of this account: asks one more question in its conversation, under its last answer, with either `prompt` or `select`. `country` and `location` carry over; leave them out or send the same values. The result carries `conversation` (`id`, `turn`, `expiresAt`) and, when it pressed a form, `selection`. Rejected before any charge with 400 VALIDATION_ERROR (another account's or engine's task, a task not completed, an invalid select) or 400 CONVERSATION_EXPIRED (after `conversation.expiresAt`, 3 hours after the conversation's first answer). select: $ref: '#/components/schemas/FollowUpSelect' description: >- With `continueFrom`, instead of `prompt`: press a follow-up form's button in the last answer of the continued task. Answers that show a form list them in `forms` (`buttons` in `button` order, `choices` with their `name`, the option selected at first and the `options`). page: type: integer minimum: 1 maximum: 10 default: 1 description: >- GOOGLE_SERP and NAVER_SERP. The results page to return, 1-10. Positions count across pages, so page 2 starts at 11 on Google and at 16 on Naver. subreddit: type: string pattern: ^[A-Za-z0-9_]{2,21}$ description: >- REDDIT only. Limits a search to one subreddit (the name without `r/`), or picks the subreddit for `action` `feed`. A feed without it lists r/popular. url: type: string format: uri description: >- REDDIT: a public post URL (`https://www.reddit.com/r/{subreddit}/comments/{postId}/...`); returns `post` with its first page of about 20-25 `comments` instead of searching. NAVER_SERP with `action` `page`: the naver.com page to read (blog, cafe, news, terms, kin or any other naver.com page). A redirect that leaves naver.com fails the task. WEB_SCRAPE: the HTML, plain-text page or text-based PDF to read, a public http or https address on the default port, up to 2,048 characters. PDFs return page-order text as `markdown`, available document metadata and `images: []`; no OCR, attachments or layout reconstruction. PDF limits: 8 MiB downloaded, 100 pages, 1,000,000 extracted characters and 20 seconds of extraction, independently of maxChars. Encrypted, damaged, incomplete, textless or over-limit PDFs fail with PAGE_UNAVAILABLE. A multi-page PDF costs 1 credit per URL. WEB_MAP and WEB_CRAWL: the site's start address, under the same rules; the host it redirects to is the site (`www.` aside). action: type: string enum: - feed - user_posts - page - search description: >- REDDIT: `feed` lists the newest posts of `subreddit`, `user_posts` lists what `username` submitted. NAVER_SERP: `page` reads `url` instead of searching. Omit it to search. username: type: string pattern: ^[A-Za-z0-9_-]{3,20}$ description: >- REDDIT with `action` `user_posts`. The Reddit username, without `u/`. limit: type: integer minimum: 1 maximum: 10000 description: >- COMMERCE_SERP: product count, integer 1-40 (default 20). REDDIT with `action` `feed` or `user_posts`: the most posts to return, 1-25 (default 25). WEB_MAP: the most addresses to return, 1-10,000 (default 1,000); `truncated` says whether the list was cut. commentSort: type: string enum: - top - new - controversial - old - qa default: top description: REDDIT post `url` only. The order of the returned comment page. commentMaxDepth: type: integer minimum: 0 maximum: 100 description: >- REDDIT post `url` only. Drops replies deeper than this; `0` keeps top-level comments only. maxChars: type: integer minimum: 1000 maximum: 200000 description: >- NAVER_SERP with `action` `page`, WEB_SCRAPE and WEB_CRAWL. The most characters to return: page text on NAVER_SERP (1,000-50,000, default 20,000), Markdown on WEB_SCRAPE (1,000-200,000, default 100,000), Markdown per page on WEB_CRAWL (1,000-50,000, default 20,000). `truncated` says whether it was cut. maxPages: type: integer minimum: 1 maximum: 100 default: 10 description: >- WEB_CRAWL. The most pages to read, the start page included. The task holds this many credits at submission and is charged 1 credit per page it returns; pages it could not read are not charged. maxDepth: type: integer minimum: 0 maximum: 5 default: 2 description: >- WEB_CRAWL. Link hops from the start page; `0` reads the start page alone. includePaths: type: array maxItems: 20 items: type: string pattern: ^/ maxLength: 200 description: >- WEB_MAP and WEB_CRAWL. Path patterns an address must match: `*` within one path segment, `**` across segments, `/blog/**` includes `/blog`. Matched against the decoded path. excludePaths: type: array maxItems: 20 items: type: string pattern: ^/ maxLength: 200 description: >- WEB_MAP and WEB_CRAWL. Path patterns that remove an address, in the same form as `includePaths`, which they override. includeSubdomains: type: boolean default: false description: WEB_MAP and WEB_CRAWL. Counts the site's subdomains as the site. keywords: type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 80 description: >- KEYWORD_VOLUME only. The keywords to count, 1-100 of up to 80 characters each; KR keywords take letters, digits and spaces. Each comes back with `searchVolume` (the 12-month average), `monthlySearches` (`{month, searchVolume}`, oldest first), `last30Days` (Naver's 30-day count, KR only) and `competition`. `country` is required, and CN and RU are refused with 422 REGION_UNSUPPORTED. example: - sunscreen - best sunscreen for face include: $ref: '#/components/schemas/Include' brand: type: string maxLength: 200 description: >- With `include.analysis`: your brand's name, reported in `analysis.targets` with role `brand`. brandAliases: type: array maxItems: 20 items: type: string maxLength: 200 description: >- With `include.analysis` and `brand`: other names the answer may use for your brand. brandDomains: type: array maxItems: 20 items: type: string description: >- With `include.analysis` and `brand`: your sites, such as `example.com`. A citation on one of them or a subdomain has `kind` `owned`. example: - example.com competitors: type: array maxItems: 50 items: oneOf: - type: string maxLength: 200 - type: object additionalProperties: false required: - name properties: name: type: string maxLength: 200 aliases: type: array maxItems: 20 items: type: string maxLength: 200 domains: type: array maxItems: 20 items: type: string description: >- With `include.analysis`: competitors reported in `analysis.targets` with role `competitor`. A citation on one of their domains has `kind` `competitor`. additionalProperties: false BatchCounts: type: object required: - pending - queued - processing - completed - failed - rejected description: >- Items by status. `pending` items wait for room in your plan's active-task limit and in the engine's queue; `rejected` items were refused when their task was created (for example `INSUFFICIENT_CREDITS`). properties: pending: type: integer queued: type: integer processing: type: integer completed: type: integer failed: type: integer rejected: type: integer FollowUpSelect: type: object additionalProperties: false description: Press a button of a ChatGPT follow-up form. properties: button: type: integer minimum: 0 default: 0 description: The button, counted from 0 across the answer's forms. choices: description: >- Options to pick by choice name, or as an array in the form's order. A pick is an option's value or label, or its position from 0. Unpicked choices keep ChatGPT's selection. oneOf: - type: object maxProperties: 20 additionalProperties: oneOf: - type: string minLength: 1 maxLength: 500 - type: integer minimum: 0 - type: array maxItems: 20 items: oneOf: - type: string minLength: 1 maxLength: 500 - type: integer minimum: 0 Include: type: object description: >- Optional output flags. `markdown`, `rawResponse`, `searchQueries`, `ads` and `shopping` are ignored by engines that do not support them. `analysis` on an unsupported engine is rejected with 422 VALIDATION_ERROR, `html` with 422 EVIDENCE_UNSUPPORTED, and `screenshot: true` with 400 VALIDATION_ERROR on every engine. See the engine guide for the support table. properties: markdown: type: boolean description: >- Adds `markdown` on CHATGPT (on by default), PERPLEXITY, GEMINI, GOOGLE (the AI Overview), BING_SEARCH (the summary) and BING_COPILOT. AIMODE, META_AI, QWEN, DOUBAO, NAVER_AI_BRIEF and NAVER_AI_TAB return `markdown` without the flag. html: type: boolean description: >- Returns `html`: `{"status": "ok", "url", "expiresAt"}`, the screen the engine showed for the answer, which opens without an API key until `expiresAt` (30 days). On GOOGLE and AIMODE it is the results page Google served, scripts removed; on CHATGPT, GEMINI, PERPLEXITY and META_AI it is the engine's screen as it showed when the answer finished, scripts removed and images included. A screen that could not be collected, did not match the answer, or could not be stored comes back as `{"status": "failed", "error": "EVIDENCE_FAILED"}` and the task still completes. Other engines reject it with 422 EVIDENCE_UNSUPPORTED, and so does CHATGPT with `location`, country `CN` or `HK`, or `continueFrom`: ChatGPT draws its page only for a new conversation answered without a device location. On CHATGPT, PERPLEXITY and META_AI it costs 0.25 credits per task on top of the engine's price, charged only when `html.status` is `ok`; on GEMINI, GOOGLE and AIMODE it costs nothing more. Off by default. rawResponse: type: boolean description: >- Returns the engine's raw payload. Arrives as `rawResponse` on CHATGPT, GEMINI, PERPLEXITY, BING_COPILOT, META_AI, QWEN and DOUBAO, and as `rawContent` on GOOGLE, AIMODE, GOOGLE_SERP, BING_SEARCH, NAVER_AI_BRIEF and NAVER_AI_TAB. NAVER_SERP, REDDIT, WEB_SCRAPE, WEB_MAP, WEB_CRAWL and KEYWORD_VOLUME return no raw payload. Off by default. searchQueries: type: boolean description: >- Gates `searchQueries` on CHATGPT (on by default) and PERPLEXITY. Other engines that emit it do so unconditionally. ads: type: boolean description: Only honored by CHATGPT. shopping: type: boolean description: Only honored by CHATGPT. citationAnalysis: type: boolean description: >- Answer engines (CHATGPT, GEMINI, PERPLEXITY, GOOGLE_AIO, GOOGLE_AIMODE, NAVER_AI_BRIEF, NAVER_AI_TAB, BING_SEARCH, BING_COPILOT): run a Citation Analysis analysis on the answer as soon as it is collected. The result then carries `response.citationAnalysis`, the analysis task as GET /v1/async/task/{id} returns it (`task`, `credits`, `response` or `error`), or `{error}` when no analysis could start (no cited URL, or credits or the key's daily limit cannot cover its hold). The webhook is sent once, after the analysis settles; a polled answer task is COMPLETED first, so poll until `response.citationAnalysis.task.status` is terminal. The analysis is charged separately by usage; a key limited to certain task types must also allow CITATION_ANALYSIS. Any other engine is rejected with 400. geoAudit: type: boolean deprecated: true description: >- Accepted alias of `citationAnalysis`; results still carry `response.citationAnalysis`. sourceInfluence: type: boolean deprecated: true description: >- Accepted alias of `citationAnalysis`; results still carry `response.citationAnalysis`. analysis: type: boolean description: >- CHATGPT, GEMINI, PERPLEXITY, GOOGLE, AIMODE, NAVER_AI_BRIEF and NAVER_AI_TAB. Adds `analysis` (AnswerAnalysis) to the response: every brand the answer names in order, with recommendation and sentiment, the presence of `brand` and `competitors`, and the kind of each cited site. 1 credit per task on top of the engine price, charged only when `analysis.status` is `ok`. Rejected with 422 on other engines. entityDetails: type: boolean description: >- CHATGPT only. Adds `entityDetails`: for each card in the answer (up to 20), the detail panel ChatGPT opens when a reader clicks it, with `name`, `category`, `query`, `status` (`ok` or `failed` with `error`), `markdown`, `sources` (`position`, `url`, `label`, `site`, `description`), `products` (the shopping card a product's panel opens on, shaped like `shoppingCards[].products`), `images` and `complete` (`false` when ChatGPT stopped writing the panel early). `error` is `ENTITY_DETAIL_FAILED`, `ENTITY_DETAIL_EMPTY`, or `ENTITY_DETAIL_UNAVAILABLE` when the conversation or turn credentials needed to open panels are missing. Supports tasks with `payload.location`, CN, HK, fallback answers and `html`. No extra credits; each follow-up answer gets its own panels. Rejected with 422 on other engines. Off by default. aioverview: type: object description: >- Legacy GOOGLE flag. `aioverview.markdown: true` works like `include.markdown` on GOOGLE. properties: markdown: type: boolean screenshot: type: boolean description: >- No longer available. `true` is rejected with 400 VALIDATION_ERROR; use `html` for a page of the answer. additionalProperties: false 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.