> ## 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.

# Ejecutar una tarea en modo síncrono

> Envía una sola tarea y recibe su resultado en la misma solicitud, en un máximo de 290 segundos.



## OpenAPI

````yaml POST /v1/sync/task
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/sync/task:
    post:
      tags:
        - Tasks
      summary: Run a task and wait for its result
      description: >-
        Submit a single task and get its result in the same request. The body,
        validation and price are those of `POST /v1/async/task`. When the task
        ends, the response is `200` with the body `GET /v1/async/task/{id}`
        returns, a failed task included.


        The request is held for up to 290 seconds. Send `Prefer: wait=<seconds>`
        to hold it for less, for example below your HTTP client's timeout.
        Answer engines can use the whole wait; for SERP and search tasks,
        `Prefer: wait=120` is enough. A task that has not ended by then is
        answered with `202`, the task, and `Location: /v1/async/task/{id}`. It
        keeps running and is charged as usual, so poll that address for the
        result. A `202` can also come at once while the service is holding many
        requests.


        Sending the same `idempotencyKey` again answers with the task that holds
        the key instead of `409`, so a request your client gave up on can be
        sent again without running the task twice.


        With `Accept: text/html` and `payload.include.html: true`, a completed
        task is answered with its saved page as `text/html`, and the `X-Task-Id`
        header carries the task id.
      operationId: runTaskSync
      parameters:
        - name: Prefer
          in: header
          required: false
          description: >-
            `wait=<seconds>` holds the request at most that long, up to 290.
            `wait=0` answers with the task id at once.
          schema:
            type: string
            example: wait=120
        - name: Accept
          in: header
          required: false
          description: >-
            `text/html` answers with the task's saved page and needs
            `payload.include.html: true`. Any other value answers with JSON.
          schema:
            type: string
            enum:
              - application/json
              - text/html
            default: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsyncRequest'
            examples:
              googleSerpPage:
                summary: >-
                  Google results page 2 with its saved page, searched from
                  Austin, Texas
                value:
                  taskType: GOOGLE_SERP
                  idempotencyKey: check-42:page-2
                  payload:
                    query: best crm for small business
                    country: US
                    page: 2
                    uule: w+CAIQICIaQXVzdGluLFRleGFzLFVuaXRlZCBTdGF0ZXM
                    include:
                      html: true
              googlePlacesPage:
                summary: Third page of Google Places, places 41 to 60 (1 credit)
                value:
                  taskType: GOOGLE_PLACES
                  payload:
                    query: Reno attorney
                    city: Reno, Nevada, United States
                    page: 3
              llm:
                summary: LLM engine (reads payload.prompt)
                value:
                  taskType: GEMINI
                  idempotencyKey: job-42:prompt-7:gemini
                  priority: 1
                  webhook:
                    url: https://your-server.example.com/hook
                  payload:
                    prompt: best wireless earbuds 2026
                    country: US
                    include:
                      markdown: true
      responses:
        '200':
          description: >-
            The task ended: the body `GET /v1/async/task/{id}` returns, with
            `response` or `error`. With `Accept: text/html`, the saved page of
            the completed task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
              examples:
                completed:
                  summary: Completed
                  value:
                    success: true
                    task:
                      id: 8f2c1e40-0000-0000-0000-000000000000
                      taskType: GEMINI
                      status: COMPLETED
                      priority: 1
                      createdAt: '2026-07-09T04:12:00.000Z'
                      latencyMs: 8412
                    credits:
                      creditsToCharge: 1.25
                      creditsCharged: 1.25
                    response:
                      text: The best wireless earbuds in 2026 are ...
                      sources:
                        - position: 1
                          url: https://example.com/review
                          label: Best earbuds, reviewed
                naverUpstreamError:
                  summary: Naver answer preserved with an upstream error
                  description: Collection finished; the answer may be incomplete.
                  value:
                    success: true
                    task:
                      id: 8f2c1e40-0000-0000-0000-000000000000
                      taskType: NAVER_AI_TAB
                      status: COMPLETED
                      priority: 1
                      createdAt: '2026-07-09T04:12:00.000Z'
                      latencyMs: 8412
                    credits:
                      creditsToCharge: 1.25
                      creditsCharged: 1.25
                    response:
                      text: '2'
                      markdown: '2'
                      sources: []
                      upstreamError:
                        type: unknown_error
                failed:
                  summary: 'Failed: `error` is a string here, not an object'
                  value:
                    success: true
                    task:
                      id: 8f2c1e40-0000-0000-0000-000000000000
                      taskType: GEMINI
                      status: FAILED
                      priority: 1
                      createdAt: '2026-07-09T04:12:00.000Z'
                      latencyMs: 8412
                    credits:
                      creditsToCharge: 0
                      creditsCharged: 0
                    error: >-
                      ENGINE_TIMEOUT: The engine did not answer before the task
                      deadline.
            text/html:
              schema:
                type: string
              example: >-
                <!doctype html>

                <!-- Saved by querying.ai: the page Google Search served for
                task 8f2c1e40-... -->

                <html>...</html>
        '202':
          description: >-
            The task had not ended when the wait was over. It keeps running;
            poll `Location` or wait for the webhook.
          headers:
            Location:
              description: 'Where to poll the task: `/v1/async/task/{id}`.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
              example:
                success: true
                task:
                  id: 8f2c1e40-0000-0000-0000-000000000000
                  taskType: GEMINI
                  status: QUEUED
                  priority: 1
                  createdAt: '2026-07-09T04:12:00.000Z'
                  latencyMs: null
                credits:
                  creditsToCharge: 0
                  creditsCharged: 0
        '400':
          description: >-
            `VALIDATION_ERROR`: malformed body, unrecognised `taskType`, a
            missing or invalid field (`details` names it), or an invalid
            `webhook.url`. `USE_DEDICATED_ENDPOINT`: CITATION_ANALYSIS and
            PROMPT_RESEARCH are created through `POST /v1/citation-analysis` and
            `POST /v1/prompt-research`, and a search through `POST /v1/search`.
            `CONVERSATION_EXPIRED`: the ChatGPT conversation named by
            `payload.continueFrom` can no longer be continued. With `Accept:
            text/html`, a body without `payload.include.html: true` is refused
            before a task is created (`details` names `payload.include.html`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  details:
                    - field: payload.prompt
                      message: payload.prompt or payload.query is required
                  timestamp: '2026-07-09T04:12:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: '`INSUFFICIENT_CREDITS`: the balance is below the price of the task.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INSUFFICIENT_CREDITS
                  message: insufficient credits (need 2)
                  timestamp: '2026-07-09T04:12:00.000Z'
        '403':
          description: >-
            `KEY_SCOPE_DENIED`: the engine is outside the key's Allowed engines.
            `ENGINE_PRIVATE`: the `taskType` is not available on self-serve
            plans; `details.availableTaskTypes` lists the ones that are.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                keyScope:
                  summary: Engine outside the key's scope
                  value:
                    success: false
                    error:
                      code: KEY_SCOPE_DENIED
                      message: This API key is not allowed to submit taskType 'GEMINI'
                      timestamp: '2026-07-09T04:12:00.000Z'
                enginePrivate:
                  summary: Engine not sold on self-serve plans
                  value:
                    success: false
                    error:
                      code: ENGINE_PRIVATE
                      message: taskType 'CLAUDE' is not available on self-serve plans
                      details:
                        taskType: CLAUDE
                        retryable: false
                        availableTaskTypes:
                          - CHATGPT
                          - GEMINI
                          - ...
                      timestamp: '2026-07-09T04:12:00.000Z'
        '406':
          description: >-
            With `Accept: text/html`, the task ended without a saved page: it
            failed, or its page could not be saved. The body is the JSON answer,
            as in `200`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '409':
          description: >-
            A task with this `idempotencyKey` exists but is past its retention
            window, so its result can no longer be read. A key whose task can
            still be read is answered with that task instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: RESOURCE_ALREADY_EXISTS
                  message: Task already exists.
                  details:
                    taskId: 8f2c1e40-0000-0000-0000-000000000000
                  timestamp: '2026-07-09T04:12:00.000Z'
        '413':
          description: >-
            `PAYLOAD_TOO_LARGE`: the body exceeds 1 MiB. Rejected before
            parsing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: PAYLOAD_TOO_LARGE
                  message: request body exceeds 1 MiB
                  timestamp: '2026-07-09T04:12:00.000Z'
        '422':
          $ref: '#/components/responses/RegionUnavailable'
        '429':
          description: >-
            Retry after the `Retry-After` header (seconds).
            `QUEUE_LIMIT_EXCEEDED`: the account already has 1,000,000 queued
            tasks. `KEY_DAILY_CREDIT_LIMIT`: the key used up its daily credit
            limit. `SUB_ACCOUNT_CREDIT_LIMIT`: the sub-account would exceed its
            `monthlyCreditLimit`. A task past the plan or contract concurrency
            limit is not refused: it is accepted, polls as `QUEUED`, and starts
            as running tasks finish.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: QUEUE_LIMIT_EXCEEDED
                  message: >-
                    Queue limit exceeded. Maximum 1000000 queued tasks allowed
                    per account
                  details:
                    limit: 1000000
                    retryAfterSec: 30
                  timestamp: '2026-07-09T04:12:00.000Z'
        '503':
          description: >-
            Retry after the `Retry-After` header (seconds).
            `QUEUE_BACKPRESSURE`: this engine's queue is full.
            `SERVER_OVERLOADED`: admission is saturated, or the task queue as a
            whole is full. `DB_UNAVAILABLE`: task storage did not answer.
            `ENGINE_UNAVAILABLE`: this engine is temporarily not accepting
            tasks; `details.resumeAt`, when present, is when it expects to take
            tasks again. `EVIDENCE_UNAVAILABLE`: HTML pages of answers are not
            available right now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: DB_UNAVAILABLE
                  message: Task storage unavailable. Retry shortly.
                  details:
                    retryAfterSec: 2
                    retryable: true
                  timestamp: '2026-07-09T04:12:00.000Z'
components:
  schemas:
    AsyncRequest:
      type: object
      required:
        - taskType
        - payload
      allOf:
        - $ref: '#/components/schemas/TaskInput'
      properties:
        taskType:
          $ref: '#/components/schemas/TaskSubmissionType'
        idempotencyKey:
          type: string
          description: >-
            Optional. Deduplicates submissions for at least 30 days after the
            request. Omit for no deduplication. A duplicate is a `409` on this
            endpoint, but a success on the batch endpoint.
        priority:
          type: integer
          description: >-
            Compatibility field; does not guarantee execution order. Values
            outside 1–10 are clamped, not rejected.
          minimum: 1
          maximum: 10
          default: 1
        webhook:
          type: object
          description: Optional. Omit to collect the result by polling instead.
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              description: Receives a POST when the task reaches a terminal state.
        payload:
          type: object
          description: >-
            The payload for the selected taskType; see TaskInput for the
            engine-specific schema.
      additionalProperties: false
    TaskResponse:
      type: object
      required:
        - success
        - task
        - credits
      allOf:
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: COMMERCE_SERP
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/CommerceSerpResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: COMMERCE_PRODUCT
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/CommerceProductResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: GOOGLE_PLACES
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/GooglePlacesResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: GOOGLE_NEWS
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/GoogleNewsResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: SEARCH
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/SearchResult'
      properties:
        success:
          type: boolean
          const: true
        task:
          $ref: '#/components/schemas/TaskMeta'
        credits:
          $ref: '#/components/schemas/Credits'
        response:
          type: object
          description: >-
            The engine-specific result. Absent until the task is terminal. See
            the Engines guide for per-engine shapes. NAVER_AI_TAB preserves the
            original text, markdown, sources and cards when Naver returns HTTP
            success, a valid stream ending in done, and nonempty answer text
            with unknown_error. It includes upstreamError and returns
            immediately without retrying or rephrasing, even with retryQuery.
            COMPLETED means collection finished; the answer may still be
            incomplete. Empty, cut-off or malformed streams still fail. Policy
            refusals complete with a policy_declined notice. rawContent is
            returned only with include.rawResponse. With
            `include.citationAnalysis`, answer results also carry
            `citationAnalysis` (see Include). CITATION_ANALYSIS returns
            CitationAnalysisResult; see the Citation Analysis guide.
            PROMPT_RESEARCH returns PromptResearchResult; see the Prompt
            Research guide. GEO_SCORE returns GeoScoreResult; see the GEO Score
            guide. Answer engines with `include.analysis` add `analysis`
            (AnswerAnalysis).
          properties:
            upstreamError:
              $ref: '#/components/schemas/NaverAiTabUpstreamError'
          additionalProperties: true
        error:
          type: string
          description: >-
            Present when `task.status` is `FAILED`. A plain string, not the
            `{code, message, timestamp}` object used by request-level errors.
    AsyncResponse:
      type: object
      required:
        - success
        - task
        - credits
      properties:
        success:
          type: boolean
          const: true
        task:
          $ref: '#/components/schemas/TaskMeta'
        credits:
          $ref: '#/components/schemas/Credits'
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
    TaskInput:
      type: object
      required:
        - taskType
        - payload
      oneOf:
        - properties:
            taskType:
              const: COMMERCE_SERP
            payload:
              $ref: '#/components/schemas/CommerceSerpPayload'
        - properties:
            taskType:
              const: COMMERCE_PRODUCT
            payload:
              $ref: '#/components/schemas/CommerceProductPayload'
        - properties:
            taskType:
              not:
                enum:
                  - COMMERCE_SERP
                  - COMMERCE_PRODUCT
            payload:
              $ref: '#/components/schemas/Payload'
    TaskSubmissionType:
      description: >-
        Public task types accepted by POST /v1/async/task and its batch
        endpoints. Dedicated analysis endpoints and AI Rendering publication
        create readable tasks through their own routes.
      allOf:
        - $ref: '#/components/schemas/TaskType'
        - not:
            enum:
              - CITATION_ANALYSIS
              - GEO_AUDIT
              - SOURCE_INFLUENCE
              - CITATION_ATTRIBUTION
              - PROMPT_RESEARCH
              - SEARCH
              - WEB_SEARCH
    TaskMeta:
      type: object
      required:
        - id
        - taskType
        - status
        - priority
        - createdAt
        - latencyMs
      properties:
        id:
          type: string
          format: uuid
        taskType:
          $ref: '#/components/schemas/TaskResultType'
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          type: integer
        createdAt:
          type: string
          format: date-time
        latencyMs:
          type:
            - integer
            - 'null'
          description: >-
            Milliseconds from the worker's first pickup to the final outcome,
            excluding the queue wait. `null` until the task settles. Returned by
            polling, the webhook and the submit response alike.
        idempotencyKey:
          type: string
          description: >-
            Echoed back verbatim. **Omitted**, not null, when the caller
            supplied none.
    Credits:
      type: object
      description: >-
        Credits, with up to two decimals (for example `1.25`). The submit
        response always shows `0`: nothing is charged yet, and the task's price
        is held from your balance when it starts. Polling shows `0` until the
        task is terminal, then the settled charge: the task's price for
        COMPLETED, `0` for FAILED. A task webhook reports the same charge in
        `creditsCharged`; on a FAILED task it reports the task's price in
        `creditsToCharge` and `0` in `creditsCharged`. CITATION_ANALYSIS,
        GOOGLE_PLACES and GOOGLE_NEWS are charged by usage, up to the hold
        placed when the task starts.
      properties:
        creditsToCharge:
          type: number
        creditsCharged:
          type:
            - number
            - 'null'
    NaverAiTabUpstreamError:
      type: object
      description: >-
        Optional NAVER_AI_TAB generation error accompanying preserved answer
        text. Collection finished, but the answer may be incomplete.
      required:
        - type
      additionalProperties: false
      properties:
        type:
          type: string
          const: unknown_error
        message:
          type: string
          description: >-
            Naver's exact notice text, without translation or rewording. Omitted
            when Naver provides no notice text.
    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
    CommerceSerpPayload:
      type: object
      required:
        - site
      properties:
        site:
          type: string
          enum:
            - amazon
            - walmart
            - target
            - ebay
            - aliexpress
            - google_shopping
            - sephora
            - ulta
            - coupang
            - oliveyoung
            - 11st
            - lotteon
            - musinsa
            - kurly
            - rakuten
            - yahoo_shopping
            - qoo10
            - flipkart
            - myntra
            - nykaa
            - zalando
          description: The storefront to search. One site per task.
        query:
          type: string
          minLength: 1
          maxLength: 500
          description: The search. Send query or url, not both.
          pattern: \S
        url:
          type: string
          maxLength: 2048
          description: >-
            A listing page to read instead of searching: a Qoo10 shop page
            (https://www.qoo10.jp/shop/{shop}) with site qoo10. Returns every
            product the page shows, in page order, up to limit. Its query and
            fragment are dropped. Send query or url, not both.
          minLength: 1
          format: uri
        country:
          type: string
          description: >-
            The site's own country: US for amazon, walmart, target, ebay,
            aliexpress, google_shopping, sephora and ulta; KR for coupang,
            oliveyoung, 11st, lotteon, musinsa and kurly; JP for rakuten,
            yahoo_shopping and qoo10; IN for flipkart, myntra and nykaa; DE for
            zalando. Omit to use it; any other value is rejected with 422
            REGION_UNSUPPORTED.
        limit:
          type: integer
          minimum: 1
          maximum: 200
          description: >-
            Products to return. With query: 1-40, default 20. With url: 1-200,
            default 200.
      additionalProperties: false
      oneOf:
        - required:
            - query
          not:
            required:
              - url
          properties:
            limit:
              maximum: 40
        - required:
            - url
          not:
            required:
              - query
    CommerceProductPayload:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          maxLength: 2048
          description: >-
            A product page on amazon.com, walmart.com, target.com, sephora.com
            or ulta.com (US); amazon.co.jp (JP, site amazon); 11st.co.kr,
            lotteon.com, musinsa.com, kurly.com or oliveyoung.co.kr (KR);
            item.rakuten.co.jp, store.shopping.yahoo.co.jp or qoo10.jp (JP);
            flipkart.com, myntra.com or nykaa.com (IN); or zalando.de (DE). The
            URL picks the storefront. Product URLs that COMMERCE_SERP returns
            for these storefronts work as they are, except yahoo_shopping's
            LOHACO pages on lohaco.yahoo.co.jp. A google_shopping product is
            read from the url COMMERCE_SERP returns for it
            (google.com/search?q={query}&udm=28&gl={market}#product={productId}&title={title}),
            or from the productDetailUrl of a product in GOOGLE, GOOGLE_SERP or
            AIMODE results, which may add &productDocid={productDocid} to the
            fragment: its gl is the market, the read runs the query in that
            market's Google Shopping again, or the title when Google no longer
            lists the product for the query, opens that product's panel, and
            fails with PAGE_UNAVAILABLE when Google lists it for neither.
          minLength: 1
          format: uri
        country:
          type: string
          description: >-
            The storefront's own country: US for amazon, walmart, target,
            sephora and ulta; KR for 11st, lotteon, musinsa, kurly and
            oliveyoung; JP for rakuten, yahoo_shopping and qoo10; IN for
            flipkart, myntra and nykaa; DE for zalando. A google_shopping url
            carries its own market in gl: US, GB, AU, CA, KR, JP, TW, HK, DE,
            FR, ES, IT, PL, PT, BR, IN, ID, TH or VN. Omit to use it; any other
            value is rejected with 422 REGION_UNSUPPORTED.
      additionalProperties: false
    Payload:
      type: object
      description: >-
        Payload for non-commerce engines. Commerce requests use
        CommerceSerpPayload or CommerceProductPayload instead. Answer and search
        engines require prompt or query. 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, GOOGLE_PLACES,
            GOOGLE_NEWS, BING_SEARCH, 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.
        retryQuery:
          type: string
          minLength: 1
          maxLength: 100000
          description: >-
            NAVER_AI_TAB only. Optional alternative question to ask after Naver
            reports a generation error with no usable answer. The original
            question is asked first. An original answer preserved with
            response.upstreamError is returned immediately without retrying or
            rephrasing, even when retryQuery is provided. All attempts share the
            existing retry and time limits. If this question is used,
            response.recovery contains {reason: upstream_generation_error,
            query: <the alternative question>}; the answer belongs to that
            question. Without this field, retries keep the original question.
            Other failures and policy refusals do not activate the alternative.
            Other engines or a blank value are rejected with 400
            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
        state:
          type: string
          pattern: ^[A-Za-z]{2}$
          description: >-
            CHATGPT, BING_AIMODE, GEMINI, GOOGLE, AIMODE and GOOGLE_SERP. A US
            state as its two-letter code, case-insensitive; `GET
            /v1/states?country=US` lists them. CHATGPT and BING_AIMODE ask from
            a residential connection in the state, GEMINI asks as a device in
            its largest city, and the Google engines search with the state as
            Google's location, so local recommendations come from that state.
            Sent with `country` `US` or without `country`; another country, a
            code that is not a state, or `state` together with `uule` is
            rejected with 400 VALIDATION_ERROR, and other engines reject it with
            422 LOCATION_UNSUPPORTED. Adds 1 credit to the task. The response
            echoes it as `state`.
          example: TX
        uule:
          type: string
          pattern: ^w\+[A-Za-z0-9+/_-]{4,600}={0,2}$
          description: >-
            GOOGLE, AIMODE, GOOGLE_SERP and GOOGLE_PLACES. Google's own location
            parameter in its `w+` form, exactly as it goes into a Google search
            URL, for example `w+CAIQICIaQXVzdGluLFRleGFzLFVuaXRlZCBTdGF0ZXM` for
            Austin, Texas. It is sent to Google unchanged, so the results page,
            AI Overview and AI Mode answer for that place. Use it instead of
            `state` when your system already stores UULEs; sending both is
            rejected with 400 VALIDATION_ERROR, as is a value that is not a `w+`
            UULE (for example the percent-encoded `w%2B…`). Other engines reject
            it with 422 LOCATION_UNSUPPORTED. GOOGLE_PLACES takes no `state` and
            rejects `uule` together with `city` with 422 VALIDATION_ERROR. The
            response echoes it as `uule`.
          example: w+CAIQICIaQXVzdGluLFRleGFzLFVuaXRlZCBTdGF0ZXM
        city:
          type: string
          minLength: 1
          maxLength: 100
          description: >-
            GOOGLE_PLACES only. The place to search from, named the way Google
            names places: city, state or region, and country, for example `Reno,
            Nevada, United States`. Every Places page is searched from it. Send
            `city` or `uule`; `city` together with `uule` is rejected with 422
            VALIDATION_ERROR. The response echoes it as `city`.
          example: Reno, Nevada, United States
        pages:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
          description: >-
            GOOGLE_NEWS and GOOGLE_SERP. GOOGLE_NEWS: News pages to read, 1-10,
            10 articles each. GOOGLE_SERP: results pages to read starting at
            `page`, 1-50, all on one session and one IP address; not with
            `include.rawResponse` (422 VALIDATION_ERROR). Reading stops at
            Google's last page. Priced per page read; the task holds credits for
            every page asked for when it starts and is charged for the pages it
            read.
          example: 2
        device:
          type: string
          enum:
            - desktop
            - mobile
            - android
            - tablet
          default: desktop
          description: >-
            GOOGLE_SERP and GOOGLE_NEWS. The page Google serves: `desktop`,
            Chrome on Android as `mobile` or `android`, where `mobile` is an
            alias for `android`, or Chrome on an Android tablet as `tablet`
            (GOOGLE_SERP only). A mobile or tablet page returns the same fields
            in Google's layout for that device and costs the same credits. `ios`
            is rejected with 422 VALIDATION_ERROR, because the Google lane runs
            Chrome, not Safari.
          example: mobile
        hl:
          type: string
          maxLength: 35
          description: >-
            GOOGLE, AIMODE, GOOGLE_SERP and GOOGLE_NEWS. The interface language
            of the results page, as Google's own `hl` (`en`, `de`, `pt-BR`). It
            overrides the language derived from `country`, so the market and the
            interface language can differ. Case is normalized, `pt-br` reads as
            `pt-BR`. Values that are not a language code are rejected with 422
            VALIDATION_ERROR.
          example: de
        webSearch:
          type: boolean
          default: true
          description: >-
            CHATGPT only. false asks with ChatGPT's search toggle off, so
            ChatGPT chooses on its own when to search. Applies to every answer
            of the task, followUps included. Rejected with 422
            EVIDENCE_UNSUPPORTED together with include.html.
        images:
          type: array
          minItems: 1
          maxItems: 4
          items:
            type: string
            description: >-
              A public http(s) URL, or a data URL: data:image/jpeg, png, webp or
              gif;base64,<data>.
          description: >-
            CHATGPT only. Photos asked with the first question, the way a user
            adds them with ChatGPT's photo button: JPEG, PNG, WebP or GIF, up to
            10 MB each. A data URL counts toward the request body limit (1 MiB
            on POST /v1/async/task). followUps keep asking about the photos in
            the same conversation, at 1 credit per answer. Rejected with 400
            VALIDATION_ERROR together with country CN or HK, or continueFrom,
            and with 422 EVIDENCE_UNSUPPORTED together with include.html. Other
            engines reject it with 400 VALIDATION_ERROR. A photo that cannot be
            fetched or read fails the task with BAD_PAYLOAD.
          example:
            - https://www.example.com/photos/product.jpg
        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 `state` 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, NAVER_SERP and GOOGLE_PLACES. The results page to
            return, 1-10 (1-5 for GOOGLE_PLACES). Positions count across pages,
            so page 2 starts at 11 on Google, at 16 on Naver and at 21 on Google
            Places. GOOGLE_PLACES reads that one page alone and charges 1
            credit; send `page` or `limit`, not both (422 VALIDATION_ERROR).
        url:
          type: string
          format: uri
          description: >-
            GOOGLE_SERP, GOOGLE_AIO and GOOGLE_AIMODE: an
            https://www.google.com/search address sent in place of `query`, or
            the same address on a Google country domain such as www.google.de,
            which is asked at www.google.com with the same path and parameters;
            without gl or `country`, the domain's country is the market. An
            address without gl is asked with the market's gl added. Its q, gl,
            hl and uule are read as `query`, `country`, `hl` and `uule`, and on
            GOOGLE_SERP its start as `page`; GOOGLE_AIMODE needs udm=50. All
            three ask Google with the address exactly as written, so its other
            parameters (num, lr, tbs, filter and so on) reach Google; Google
            lists ten results a page whatever num says. An address that picks
            another tab with udm or tbm on GOOGLE_SERP or GOOGLE_AIO, one
            without udm=50 on GOOGLE_AIMODE, or one sent together with `query`,
            `hl`, `uule` or `page`, returns 422 VALIDATION_ERROR. 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. COMMERCE_SERP: a listing page read instead
            of a query, a Qoo10 shop page (https://www.qoo10.jp/shop/{shop})
            with site qoo10. WEB_SCRAPE: the public page or PDF to read.
        action:
          type: string
          enum:
            - page
            - search
          description: >-
            NAVER_SERP: `page` reads `url` instead of searching. Omit it to
            search.
        limit:
          type: integer
          minimum: 1
          maximum: 200
          description: >-
            COMMERCE_SERP: product count, integer 1-40 (default 20) with query,
            1-200 (default 200) with url. GOOGLE_PLACES: the places to return
            from the top of the list, 1-100 (default 20, one page); the task
            holds 1 credit per 20 places and is charged for the pages it read.
            Send `limit` or `page`, not both.
        maxChars:
          type: integer
          minimum: 1000
          maximum: 200000
          description: >-
            NAVER_SERP with `action` `page`. The most characters of page text to
            return: NAVER_SERP 1,000-50,000 (default 20,000), WEB_SCRAPE
            1,000-200,000 (default 100,000). `truncated` says whether it was
            cut.
        rawHtml:
          type: boolean
          description: 'WEB_SCRAPE: also return the HTML that was read as rawHtml.'
        contentHtml:
          type: boolean
          description: 'WEB_SCRAPE: also return the main content as HTML in contentHtml.'
        jsonLd:
          type: boolean
          description: >-
            WEB_SCRAPE: also return the page's schema.org JSON-LD blocks as
            jsonLd.
        render:
          type: boolean
          description: >-
            WEB_SCRAPE: read the page in a browser after its script ran, even
            when a plain request already gets it. GOOGLE_SERP with
            `include.html: true`: `html` is the results page as Chrome shows it
            once its scripts ran, with the AI Overview loaded and opened by its
            Show more, read through an exit in a country where Google shows AI
            Overviews; any `device` and `page`. Costs 1 credit on top of the
            search price, charged only when `html.status` is `ok`, and adds
            about 5 to 10 seconds. Without `include.html: true`, or as a value
            other than a boolean, it is rejected with 422 VALIDATION_ERROR.
        screenshot:
          type: boolean
          description: >-
            WEB_SCRAPE: read the page in a laptop-sized browser, scrolled to the
            end with its images drawn, and also return screenshot (a stored JPEG
            of its first four screens) and shown (its text as a person reads it,
            where each image sits, and the page as drawn). Implies render.
        maxAge:
          type: integer
          minimum: 0
          maximum: 604800000
          description: >-
            WEB_SCRAPE: accept a cached read younger than this, in milliseconds,
            up to 604,800,000 (7 days). Omit or send 0 to always read fresh.
        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
    TaskType:
      type: string
      description: >-
        The engine to query. `NAVER` is a deprecated alias for `NAVER_AI_BRIEF`.
        GOOGLE_AIO and GOOGLE_AIMODE are the names of Google AI Overviews and
        Google AI Mode; the earlier names GOOGLE and AIMODE are accepted too,
        and a task answers under the name it was sent with. `NAVER_AI_MODE` is
        accepted as an earlier spelling of `NAVER_AI_TAB`. `BING_AIMODE` returns
        Bing AI Mode's answer (bing.com/copilotsearch) for `payload.query` in
        AE, AU, BR, CA, DE, EE, ES, FR, GB, HK, HU, IE, IN, IT, JP, MX, NL, PL,
        PT, RO, RS, SE, SG, SK, TR, US and ZA, and refuses other countries with
        422 REGION_UNSUPPORTED; `BING_COPILOT_SEARCH` and `COPILOT_SEARCH` are
        accepted as its other names. `BING_COPILOT` and `MICROSOFT_COPILOT` are
        accepted as other names of `COPILOT` (Microsoft Copilot). `GOOGLE_SERP`
        returns the Google results page without the AI Overview; `payload.page`
        selects pages 1-10. `BRAVE_SEARCH` returns Brave's own results page:
        organic results, ads, FAQ, knowledge panel, news, videos, discussions,
        places and related queries, with `payload.country` from Brave's markets
        and `payload.page` from 1 to 10; there is no HTML payload, so `include`
        adds nothing. `GOOGLE_PLACES` returns the places Google's Places tab
        lists for `payload.query`, up to 100 over up to five pages of 20, every
        page searched from `payload.city` or `payload.uule`; `payload.limit`
        (1-100, default 20) sets how many, and the task is charged 1 credit per
        page read (GooglePlacesResult). `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`. `META_AI` returns the
        meta.ai chat answer with its cited sources, search queries and the
        products, places, photos and accounts it shows (`shoppingCards`,
        `inlineProducts`, `map`, `images`, `socialCards`); 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. `BAIDU_WENXIN`
        returns the answer of Baidu's Wenxin web chat (文心, wenxin.baidu.com)
        with the pages it read as sources and its search queries; it always asks
        from mainland China, whatever `payload.country` is. `BAIDU_AI_SEARCH`
        returns the AI answer card at the top of Baidu's results page for
        `payload.query`, with the pages it cites, and the rest of that page:
        organic results, ads, related searches, news, videos, notes, products,
        images, places and Baidu's other cards; it always searches from mainland
        China, and a query Baidu shows no AI answer for completes with `card:
        null` and the rest of the page. `BING` is accepted as an earlier
        spelling of `BING_SEARCH`, and `BING_COPILOT` and `MICROSOFT_COPILOT` as
        earlier spellings of `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. SEARCH is the name a search made through POST /v1/search
        answers under, and WEB_SEARCH the id capabilities, key scopes and usage
        list it by; both are rejected here with 400 USE_DEDICATED_ENDPOINT.
        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
        - GOOGLE_PLACES
        - GOOGLE_NEWS
        - NAVER_AI_BRIEF
        - NAVER_AI_TAB
        - NAVER_AI_MODE
        - NAVER
        - NAVER_SERP
        - COMMERCE_SERP
        - COMMERCE_PRODUCT
        - BING_SEARCH
        - BRAVE_SEARCH
        - BING
        - COPILOT
        - BING_COPILOT
        - MICROSOFT_COPILOT
        - BING_AIMODE
        - BING_COPILOT_SEARCH
        - COPILOT_SEARCH
        - META_AI
        - QWEN
        - DOUBAO
        - BAIDU_WENXIN
        - BAIDU_AI_SEARCH
        - CITATION_ANALYSIS
        - GEO_AUDIT
        - SOURCE_INFLUENCE
        - CITATION_ATTRIBUTION
        - PROMPT_RESEARCH
        - GEO_SCORE
        - SEARCH
        - WEB_SEARCH
        - WEB_SCRAPE
    TaskResultType:
      description: >-
        Task types returned by task polling, submissions, batch results and
        webhooks, including tasks created by dedicated endpoints. This is not a
        submission engine list.
      anyOf:
        - $ref: '#/components/schemas/TaskType'
        - type: string
          enum:
            - AI_RENDERING
    TaskStatus:
      type: string
      description: >-
        `PROCESSING` means a worker holds the task. `COMPLETED` and `FAILED` are
        terminal. For NAVER_AI_TAB with response.upstreamError, `COMPLETED`
        means collection finished; the answer may still be incomplete.
      enum:
        - QUEUED
        - PROCESSING
        - COMPLETED
        - FAILED
    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.
        `citationLinks` is PERPLEXITY only and requires `markdown: true`.
        `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 COPILOT.
            AIMODE, BING_AIMODE, META_AI, QWEN, DOUBAO, BAIDU_WENXIN,
            BAIDU_AI_SEARCH, NAVER_AI_BRIEF and NAVER_AI_TAB return `markdown`
            without the flag.
        citationLinks:
          type: boolean
          description: >-
            PERPLEXITY only, with `markdown: true`. Turns bare `[N]` citation
            markers in `markdown` into `[N](url)` links to the matching
            `sources[].url`. `text`, existing links, code, escaped markers and
            markers without a matching source stay unchanged. Off by default;
            other requests are rejected with 422 VALIDATION_ERROR.
        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 GOOGLE_SERP it is the
            document Google sent for the results page, before its scripts ran,
            with its scripts kept and session identifiers removed, or with
            `render: true` the page as Chrome shows it once its scripts ran, AI
            Overview opened (not with `pages` above 1, `state`, `uule`,
            `include.rawResponse` or `include.aiOverview`: 422
            VALIDATION_ERROR); on BING_AIMODE it is the Bing AI Mode screen made
            from the pages Bing served, the question and the answer with its
            sponsored products, scripts removed and images included; 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, COPILOT included
            since 2026-11-06 (its lane ended on Microsoft's sign-in: every
            2026-11-05 ask failed with COPILOT_SIGN_IN_REQUIRED; pages issued
            earlier stay open until they expire), and so does CHATGPT with
            `state`, country `CN` or `HK`, `continueFrom`, `webSearch: false` or
            `images`: the page comes only with a new conversation asked with web
            search on, without a device location or photos. 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, AIMODE and BING_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, COPILOT, BING_AIMODE, META_AI, QWEN,
            DOUBAO, BAIDU_WENXIN and BAIDU_AI_SEARCH, and as `rawContent` on
            GOOGLE, AIMODE, GOOGLE_SERP, BING_SEARCH, NAVER_AI_BRIEF and
            NAVER_AI_TAB. GOOGLE_PLACES and NAVER_SERP return no raw payload.
            Off by default.
        aiOverview:
          type: boolean
          description: >-
            GOOGLE_SERP only. Adds the AI Overview Google shows for the search
            as `aiOverview`: `{"text", "markdown", "sources"}`, or `null` when
            Google shows none. First page, `desktop`, without `state`,
            `location` or `uule`; other requests are rejected with 422
            VALIDATION_ERROR. Costs 1 credit on top of the search's price. Off
            by default.
        searchQueries:
          type: boolean
          description: >-
            Gates `searchQueries` on CHATGPT (on by default) and PERPLEXITY. On
            CHATGPT it also gates `mapSearchQueries`. 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, 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 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.
        serp:
          type: boolean
          description: >-
            NAVER_AI_BRIEF only. Adds the Naver results page beneath the
            briefing: `organicResults` (web documents), `shoppingResults` (price
            comparison products, ads excluded) and `contentResults` (blog, cafe,
            Knowledge iN, influencer, news and video results, ads excluded). Off
            by default, when the task returns the briefing only. No extra
            credits. Rejected with 422 on other engines.
        inlineImages:
          type: boolean
          default: true
          description: >-
            Answer engines. Set to false for `text` and `markdown` without the
            pictures the engine showed (`![caption](url)`), in the answer, each
            follow-up answer and `aioverview`. The pictures stay in `images`; a
            video thumbnail link (`[![title](thumbnail)](url)`) stays as
            `[title](url)`. An answer made only of pictures keeps them. A value
            that is not a boolean is rejected with 422.
        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'
    RegionUnavailable:
      description: >-
        The request is well-formed, but it cannot be served as asked.
        `REGION_UNSUPPORTED`: this engine never serves `payload.country`.
        `LOCATION_UNSUPPORTED`: the engine does not take `payload.state` or
        `payload.uule`. `EVIDENCE_UNSUPPORTED`: the engine cannot return
        `include.html`, or a CHATGPT task asks for it with `state`, country `CN`
        or `HK`, `continueFrom`, `webSearch: false` or `images`.
        `VALIDATION_ERROR` (422): an engine-specific field rule, such as a
        BING_SEARCH text over 4,000 characters, or `include.analysis` on an
        engine that does not support it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: REGION_UNSUPPORTED
              message: PERPLEXITY cannot be served for country='CN' ...
              details:
                taskType: PERPLEXITY
                country: CN
                retryable: false
              timestamp: '2026-07-09T04:12:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer <key>`.'

````

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