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

# Search

> Busca en la web y recibe cada resultado con los pasajes de la página que responden a la consulta, en la misma llamada. type elige una búsqueda standard (0,5 créditos) o pro (2 créditos).



## OpenAPI

````yaml POST /v1/search
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/search:
    post:
      tags:
        - Search
      summary: Search the web and read the pages that answer
      description: >-
        Answers a query with web results an agent can read at once: each
        result's address, title and snippet, a relevance score, and the passages
        of the page that answer the query. The request stays open and the
        results come back in the same call. type chooses the search: standard is
        0.5 credits and answers in about two seconds; pro is 2 credits, searches
        deeper for questions that need several sources and answers in about four
        seconds. A failed search is not charged. A search still running after 30
        seconds is answered with its task alone; read it from GET
        /v1/async/task/{id}.
      operationId: search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              standard:
                summary: A search with the defaults
                value:
                  query: how do heat pumps work in cold climates
              pro:
                summary: A pro search with ten results and longer text
                value:
                  query: EU AI Act obligations for general-purpose models
                  type: pro
                  numResults: 10
                  contents:
                    text:
                      maxCharacters: 4000
              site:
                summary: A search limited to two sites
                value:
                  query: postgres skip locked queue
                  includeDomains:
                    - postgresql.org
                    - stackoverflow.com
      responses:
        '200':
          description: >-
            The search's task with its results in response, or with error when
            the search failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
              examples:
                completed:
                  summary: A completed search
                  value:
                    success: true
                    task:
                      id: 3f0a1c52-7b1e-4c1d-9a55-0e6b9f2d4c11
                      taskType: SEARCH
                      status: COMPLETED
                      priority: 1
                      createdAt: '2026-11-15T09:00:00.000Z'
                      latencyMs: 1840
                    credits:
                      creditsToCharge: 0.5
                      creditsCharged: 0.5
                    response:
                      query: how do heat pumps work in cold climates
                      source: all
                      type: standard
                      results:
                        - url: >-
                            https://www.energy.gov/energysaver/air-source-heat-pumps
                          title: Air-Source Heat Pumps
                          snippet: >-
                            Cold-climate air-source heat pumps keep heating
                            efficiently at outdoor temperatures well below
                            freezing.
                          text: >-
                            ## Cold climates


                            A cold-climate heat pump uses a variable-speed
                            compressor to keep moving heat indoors when the air
                            outside is below freezing.
                          score: 0.93
                          publishedDate: '2026-09-12'
                          siteName: Energy.gov
        '400':
          description: >-
            VALIDATION_ERROR: the body is not a JSON object, has a field this
            endpoint does not take, or contents is not text: true or text: {
            maxCharacters }; details names the field as it was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Request rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Not enough credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API key is not allowed to use Search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A task with this idempotencyKey already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            VALIDATION_ERROR for a field whose value is missing, of the wrong
            type or out of range, such as a userLocation that is not a
            two-letter code; details names the field as it was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Request rejected; retry after Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Request rejected; retry after Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      additionalProperties: false
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 400
          description: >-
            The search, up to 400 characters. Supports the operators
            site:example.com, -site:example.com, after:YYYY-MM-DD and
            before:YYYY-MM-DD; the date operators keep results to pages
            published between those days.
        type:
          type: string
          enum:
            - standard
            - pro
          default: standard
          description: >-
            standard answers in about two seconds. pro is a deeper search for
            questions that need several sources and answers in about four
            seconds. A standard search is 0.5 credits and a pro search 2.
        numResults:
          type: integer
          minimum: 1
          maximum: 10
          default: 5
          description: How many results to return.
        contents:
          type: object
          additionalProperties: false
          description: >-
            What each result carries of its page. Every result carries text; set
            text.maxCharacters to change how much.
          properties:
            text:
              oneOf:
                - type: boolean
                  const: true
                  description: Keeps the default of 2,000 characters.
                - type: object
                  additionalProperties: false
                  properties:
                    maxCharacters:
                      type: integer
                      minimum: 200
                      maximum: 10000
                      default: 2000
                      description: >-
                        The most characters of page text one result carries in
                        text.
        userLocation:
          type: string
          pattern: ^[A-Za-z]{2}$
          description: >-
            The market the results are for, a two-letter country code. Leave it
            out unless the results must be one country's: a search without it
            answers fastest, in the query's language.
        includeDomains:
          type: array
          maxItems: 20
          items:
            type: string
          description: >-
            Host names. Only results on these sites, subdomains included, are
            returned.
        excludeDomains:
          type: array
          maxItems: 20
          items:
            type: string
          description: Host names. Results on these sites are left out.
        idempotencyKey:
          type: string
          description: >-
            Optional. Deduplicates submissions for at least 30 days after the
            request; a duplicate is a 409.
        priority:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: Optional. Echoed in task metadata; values outside 1-10 are clamped.
        webhook:
          type: object
          description: Optional. Without it, collect the result by polling.
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              description: Receives a POST when the task reaches a terminal state.
    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.
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
    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
    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
    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
  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.