> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> POST /v1/search reference: search the web and datasets such as SEC filings, PubMed and patents. Every parameter, source filter, response field and error code.

Retrieve ranked results with source URLs and extracted content. Use Search when your application controls the queries, evidence selection and final response.

Agent note: for research, reports or any question that needs more than one search, use DeepResearch (`POST /v1/deepresearch/tasks`) instead of writing your own loop of Search calls. Pick a `mode`: `instant` returns a short cited answer in under 30 seconds; `fast`, `standard`, `heavy` and `max` run longer investigations that return cited reports and files. Use Search when your own model needs raw results to reason over. Docs index: [/llms.txt](https://docs.valyu.ai/llms.txt). Append `.md` to any page URL for Markdown. Docs MCP server: `https://docs.valyu.ai/mcp`. Integration guide for coding agents: [/AGENTS.md](https://docs.valyu.ai/AGENTS.md).

## Choose the source boundary

Use `search_type="web"` for web pages or `"news"` for news. Use `included_sources` to select dataset IDs, supported presets or domains. The `"proprietary"` option is the API's name for its dataset search route; it does not mean every source contains privately owned or exclusive information.

By default, `included_sources` is advisory: when you list two or more dataset IDs, Valyu may search only the most relevant of them for the query. To search every listed dataset, set `scope_policy: "strict"` and pass 1-128 dataset IDs (no presets, domains or `"web"`). Strict responses include a `source_scope` receipt showing which datasets were searched and which returned results. A dataset with no results was not necessarily searched in full. `scope_policy` is not in the SDKs yet, so send it over HTTP.

`excluded_sources` accepts domains, dataset IDs and preset names such as `"finance"`. Restrict domains with `included_sources` and `excluded_sources`, not `site:` in the query: a `site:` or `-site:` term is enforced as a hard filter on every result, web and dataset alike, and can remove every dataset result.

Check [available sources](https://docs.valyu.ai/api-reference/endpoint/datasources-list.md) before relying on a dataset. Request `include_abstracts=true` to expand PubMed searches beyond papers with available full text. More returned characters do not guarantee access to a complete document.

## Remove image links

Set `include_image_links` to `false` to replace each image with its alt text. For example, `![Product photo](https://example.com/p.jpg)` becomes `[Image: Product photo]`. The API removes an image with no alt text. Other links do not change. The default is `true`. See [remove image links](https://docs.valyu.ai/search/tips-and-tricks.md#remove-image-links-to-save-tokens).

## Use the results

Keep each result's `url`, `source` and available date alongside its `content`. Handle empty result sets explicitly. Read `warnings` too: it says what was skipped or adjusted, for example named datasets outside your plan. See [warnings](https://docs.valyu.ai/api-reference/warnings.md). A relevance score measures the match to a query, not the truth of a claim.

`total_deduction_dollars` is the amount charged for the request and each result's `price` is its share. Web results use 0.1 credits each; dataset prices are listed in [Datasources](https://docs.valyu.ai/api-reference/endpoint/datasources-list.md). See [pricing](https://docs.valyu.ai/pricing.md).

Start with a specific question and five results, then adjust source filters and result length against representative tasks. Use [DeepResearch](https://docs.valyu.ai/api-reference/endpoint/deepresearch-create.md) when you want to run the investigation and receive a report.


## OpenAPI

````yaml POST /v1/search
openapi: 3.0.3
info:
  title: Valyu API
  version: 2.3.0
  description: >
    The search API built for AI agents. One API that gives your AI unified
    access to web search, academic papers, financial data, SEC filings, clinical
    trials, patents, genomics, and 40+ proprietary data sources.


    ## Products


    | Product | Endpoint | Description |

    | --- | --- | --- |

    | **Search** | `POST /v1/search` | Multi-source search across web and
    proprietary datasets |

    | **Contents** | `POST /v1/contents` | Extract clean, structured content
    from URLs |

    | **Answer** | `POST /v1/answer` | AI-powered answers with real-time search
    |

    | **DeepResearch** | `POST /v1/deepresearch/tasks` | Async research agents
    for comprehensive analysis |

    | **Workflows** (Beta) | `GET /v1/workflows` | Templated, versioned
    DeepResearch for repeatable knowledge work |

    | **Datasources** | `GET /v1/datasources` | Discover available data sources
    and their schemas |


    ## Authentication


    All endpoints require an API key passed via the `X-API-Key` header (the
    lowercase `x-api-key` form is also accepted). Get your key at
    [platform.valyu.ai](https://platform.valyu.ai).


    ```

    X-API-Key: your_api_key_here

    ```


    ## Pricing


    Pay per use in credits. One credit balance covers every API.

    - **Search**: priced per result returned. Web and news results use 0.1
    credits each (100 per 1,000 results). arXiv, PubMed, bioRxiv and medRxiv use
    0.05 credits each (50 per 1,000). Other datasets have their own price per
    1,000 results, listed in `GET /v1/datasources` (`pricing.cpm`).

    - **Contents**: 0.2 credits per successfully extracted URL. Any AI
    processing (a text summary or structured extraction through `summary`)
    brings the price to 0.6 credits per URL in total, the same for both. Failed
    URLs are free.

    - **Answer**: no per-request fee. You pay for the search, content extraction
    and AI processing each answer uses, reported in
    `cost.total_deduction_dollars`.

    - **DeepResearch**: fixed price per task by mode: instant 8 credits, fast
    25, standard 100, heavy 500, max 2,500, plus tool add-ons.


    Every plan includes web search and open academic sources. Paid plans unlock
    specialist sources such as SEC filings, clinical trials, patents and
    genomics. See [pricing](https://docs.valyu.ai/pricing) for plans and free
    credits.


    ## Rate limits


    Limits apply per organisation: 10 requests per second with bursts up to 20,
    and 86,400 requests per day by default. Enterprise plans can raise them. A
    request over the limit is currently rejected with `403 Forbidden` and the
    body `{"error": "Forbidden", "message": "Access denied - API key is invalid,
    disabled, or revoked"}`. If a key that otherwise works starts receiving 403
    under load, reduce concurrency and retry with exponential backoff.


    ## SDKs


    - [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu`

    - [TypeScript SDK](https://www.npmjs.com/package/valyu-js) - `npm install
    valyu-js`
  contact:
    name: Valyu Support
    url: https://valyu.ai
    email: support@valyu.ai
  x-logo:
    url: https://valyu.ai/logo.png
    altText: Valyu
servers:
  - url: https://api.valyu.ai
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: >-
      Search across web, academic, financial, and proprietary data sources.
      Returns results ready for RAG pipelines, AI agents, and applications.
    externalDocs:
      description: Search API Guide
      url: https://docs.valyu.ai/search/quickstart
  - name: Contents
    description: >-
      Extract clean, structured content from web pages at scale. Supports batch
      processing, AI-powered summaries, structured extraction via JSON schemas,
      and async jobs for large URL sets.
    externalDocs:
      description: Contents API Guide
      url: https://docs.valyu.ai/guides/content-extraction
  - name: Answer
    description: >-
      Get AI-powered answers grounded in real-time search results. The Answer
      API searches across web, academic, and financial sources, then uses AI to
      generate a readable response via Server-Sent Events streaming.
    externalDocs:
      description: Answer API Guide
      url: https://docs.valyu.ai/guides/answer-api
  - name: DeepResearch
    description: >-
      Async research agents that perform comprehensive, multi-step research.
      DeepResearch searches multiple sources, analyzes content, and generates
      detailed reports with citations. Tasks run in the background and can take
      minutes to complete.
    externalDocs:
      description: DeepResearch Guide
      url: https://docs.valyu.ai/guides/deepresearch
  - name: Batches
    description: >-
      Run multiple DeepResearch tasks in parallel with shared configuration,
      unified monitoring, and aggregated cost tracking.
    externalDocs:
      description: Batch API Guide
      url: https://docs.valyu.ai/guides/deepresearch-batch-quickstart
  - name: Workflows
    description: >-
      **Beta.** Templated, versioned DeepResearch for repeatable knowledge work
      - earnings previews, diligence reads, market sizings. A workflow bundles a
      prompt template with typed variables, a research strategy, report format,
      deliverables, tools, and a recommended mode. Workflows are immutably
      versioned; runs can pin a version. Two scopes exist: your organization's
      private workflows and curated Valyu workflows available to everyone. Run a
      workflow by passing `workflow_id` + `workflow_params` to `POST
      /v1/deepresearch/tasks` - same auth, billing, and task lifecycle as
      freeform DeepResearch.
    externalDocs:
      description: Workflows Guide (Beta)
      url: https://docs.valyu.ai/guides/workflows
  - name: Datasources
    description: >-
      Discover available data sources and their schemas. A tool manifest for AI
      agents - instead of hardcoding knowledge of available datasets, agents can
      query this API to discover sources, filter by category, and use
      `example_queries` for few-shot prompting.
    externalDocs:
      description: Datasources Guide
      url: https://docs.valyu.ai/guides/datasources
externalDocs:
  description: Complete API Documentation
  url: https://docs.valyu.ai
paths:
  /v1/search:
    post:
      tags:
        - Search
      summary: Search across web and proprietary data sources
      description: >-
        Search web pages and available academic, financial and specialist
        datasets. Returns ranked results with source URLs and extracted content
        for your application. Use source controls to choose the retrieval scope
        and inspect the catalog for source availability.


        Use Search when you control downstream reasoning. Use
        [DeepResearch](https://docs.valyu.ai/guides/deepresearch) when you want
        to delegate an investigation and receive a report.
      operationId: search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              basic:
                summary: Basic web search
                value:
                  query: latest developments in quantum computing
                  max_num_results: 5
              academic:
                summary: Academic paper search
                value:
                  query: CRISPR gene editing clinical trials 2024
                  search_type: proprietary
                  max_num_results: 10
                  included_sources:
                    - medical
              filtered:
                summary: Source-filtered search with date range
                value:
                  query: climate change impact on agriculture
                  included_sources:
                    - valyu/valyu-arxiv
                    - valyu/valyu-pubmed
                    - valyu/valyu-biorxiv
                  start_date: '2024-01-01'
                  end_date: '2024-12-31'
                  max_num_results: 10
              pubmed_abstracts:
                summary: PubMed abstract search
                value:
                  query: clonal hematopoiesis cardiovascular disease
                  included_sources:
                    - valyu/valyu-pubmed
                  include_abstracts: true
                  max_num_results: 10
              fast:
                summary: Low-latency web search
                value:
                  query: Tesla stock price today
                  fast_mode: true
                  max_num_results: 5
              strict:
                summary: Search every listed dataset (strict scope)
                value:
                  query: GLP-1 receptor agonist cardiovascular outcomes
                  included_sources:
                    - valyu/valyu-pubmed
                    - valyu/valyu-arxiv
                  scope_policy: strict
                  max_num_results: 10
      responses:
        '200':
          description: Search completed successfully with results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              examples:
                success:
                  summary: Illustrative response with two results; not live findings
                  value:
                    success: true
                    error: null
                    tx_id: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    query: latest developments in quantum computing
                    results:
                      - id: https://example.com/research/source-1
                        title: Illustrative research source 1
                        url: https://example.com/research/source-1
                        content: >-
                          Illustrative source 1 text. Replace this placeholder
                          with the actual returned evidence.
                        description: Placeholder source text for the response format.
                        source: web
                        price: 0.000625
                        length: 87
                        image_url: {}
                        relevance_score: 0.95
                        data_type: unstructured
                        source_type: website
                        publication_date: '2024-06-15'
                      - id: https://example.com/research/source-2
                        title: Illustrative research source 2
                        url: https://example.com/research/source-2
                        content: >-
                          Illustrative source 2 text. Replace this placeholder
                          with the actual returned evidence.
                        description: Placeholder source text for the response format.
                        source: valyu/valyu-arxiv
                        price: 0.0003125
                        length: 87
                        image_url: {}
                        relevance_score: 0.89
                        data_type: unstructured
                        source_type: paper
                        publication_date: '2024-01-15'
                    results_by_source:
                      web: 1
                      proprietary: 1
                    total_deduction_dollars: 0.0009375
                    total_characters: 174
                fast_mode:
                  summary: Illustrative fast-mode response with one result
                  value:
                    success: true
                    error: null
                    tx_id: tx_fast12345-6789-abcd-ef01-234567890abc
                    query: Tesla stock price today
                    results:
                      - id: https://example.com/market-update
                        title: Illustrative market update
                        url: https://example.com/market-update
                        content: >-
                          Placeholder market information; not a live price
                          quote.
                        source: web
                        price: 0.000625
                        length: 55
                        data_type: unstructured
                        source_type: website
                    results_by_source:
                      web: 1
                    total_deduction_dollars: 0.000625
                    total_characters: 55
                strict_scope:
                  summary: >-
                    Illustrative strict-scope response with a source_scope
                    receipt
                  value:
                    success: true
                    error: null
                    tx_id: tx_strict12-3456-7890-abcd-ef1234567890
                    query: GLP-1 receptor agonist cardiovascular outcomes
                    results:
                      - id: https://example.com/research/source-3
                        title: Illustrative research source 3
                        url: https://example.com/research/source-3
                        content: >-
                          Illustrative source 3 text. Replace this placeholder
                          with the actual returned evidence.
                        source: valyu/valyu-pubmed
                        price: 0.0003125
                        length: 87
                        data_type: unstructured
                        source_type: paper
                    results_by_source:
                      web: 0
                      proprietary: 1
                    total_deduction_dollars: 0.0003125
                    total_characters: 87
                    source_scope:
                      policy: strict
                      allowed_dataset_ids:
                        - valyu/valyu-arxiv
                        - valyu/valyu-pubmed
                      selected_dataset_ids:
                        - valyu/valyu-arxiv
                        - valyu/valyu-pubmed
                      completed_dataset_ids: []
                      returned_dataset_ids:
                        - valyu/valyu-pubmed
                      omitted_dataset_ids: []
                      selection_basis: dispatch_requested
                      coverage: unknown
                      exhaustive: false
                      errors: []
        '206':
          description: >-
            Partial success - some sources failed or no results found, but the
            request was processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: The request was malformed or contained invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_parameter:
                  summary: Invalid parameter
                  value:
                    success: false
                    error: >-
                      Invalid search_type. Must be 'all', 'web', 'proprietary',
                      or 'news'
                max_price:
                  summary: max_price below the worst-case cost
                  value:
                    success: false
                    error: >-
                      Insufficient max_price. Search requires max_price >= 6.25
                      for your query
                sub_day_dates:
                  summary: Sub-day dates without historical_cache
                  value:
                    success: false
                    error: >-
                      Sub-day timestamps in start_date/end_date require
                      historical_cache=true. Use YYYY-MM-DD for standard search.
                invalid_scope_policy:
                  summary: scope_policy is not advisory or strict
                  value:
                    success: false
                    error: invalid_scope_policy
                invalid_strict_source_scope:
                  summary: Strict scope without a valid list of dataset IDs
                  value:
                    success: false
                    error: invalid_strict_source_scope
                unsupported_strict_source:
                  summary: Strict scope names a dataset Search cannot serve
                  value:
                    success: false
                    error: unsupported_strict_source
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          description: >-
            The key is disabled, revoked or lacks permission, or the requested
            sources are not available to this key.


            - `tier_insufficient` - every requested dataset is above your plan.
            If only some are, those are skipped, the rest are searched and the
            response carries a `datasets_not_in_plan` warning. `recovery` has
            `current_plan`, `required_plan` (`{id, name, price}` or `null`),
            `required_tier` and `upgrade_url`.

            - `dataset_unavailable` - every requested dataset is licensed or
            unknown. `recovery` has `current_plan`, `contact_url` and
            `datasources_url`.

            - `dataset_outside_task_scope` - with `scope_policy: "strict"`, at
            least one listed dataset is outside your plan or grants. Strict
            scope never falls back to a partial search.

            - `deepresearch_only` - every requested dataset is
            DeepResearch-only. Mixed with other sources, DeepResearch-only
            datasets are skipped with a `datasets_deepresearch_only` warning.


            A request over the rate limit returns `429`, not `403`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden:
                  summary: Key disabled or revoked
                  value:
                    error: Forbidden
                    message: Access denied - API key is invalid, disabled, or revoked
                tier_insufficient:
                  summary: Requested datasets are above your plan
                  value:
                    success: false
                    error: >-
                      Your current plan (tier_1) does not include access to:
                      valyu/valyu-clinical-trials. Upgrade your plan to access
                      these data sources.
                    code: tier_insufficient
                    recovery:
                      current_plan: tier_1
                      required_plan:
                        id: tier_2
                        name: Comfortably Pro
                        price: $99/mo
                      required_tier: tier_2
                      upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
                      available_datasets:
                        - valyu/valyu-arxiv
                        - valyu/valyu-biorxiv
                        - valyu/valyu-medrxiv
                        - valyu/valyu-pubmed
                dataset_outside_task_scope:
                  summary: Strict scope includes a dataset outside your access
                  value:
                    success: false
                    error: dataset_outside_task_scope
                deepresearch_only:
                  summary: >-
                    Only DeepResearch-only datasets requested (illustrative
                    dataset ID)
                  value:
                    success: false
                    error: >-
                      One or more requested datasets are only available through
                      DeepResearch.
                    restricted_sources:
                      - example/deepresearch-only-dataset
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      additionalProperties: false
      description: Search request parameters.
      properties:
        query:
          type: string
          description: The search query to execute. Supports natural language queries.
          example: latest developments in quantum computing
        max_num_results:
          type: integer
          description: >-
            Maximum number of results to return. Higher limits (up to 100) are
            available on request. A value above your limit is lowered to it, and
            the response carries a `max_num_results_capped` warning.
          default: 5
          minimum: 1
          maximum: 20
          example: 10
        search_type:
          type: string
          description: >-
            Controls which data sources are searched.


            - `all` - Web and proprietary sources (default). An LLM router
            selects the best sources for your query.

            - `web` - Web search only. Best for current events and general
            topics.

            - `proprietary` - Academic, financial, and premium sources only.
            Best for research and technical analysis.

            - `news` - News articles only. Best for recent news and current
            events.
          enum:
            - all
            - web
            - proprietary
            - news
          default: all
          example: all
        max_price:
          type: number
          description: >-
            Caps the cost of the whole request. This is not a token limit or a
            per-result ceiling. When omitted, the default is 1000. See
            [pricing](https://docs.valyu.ai/pricing).


            Before searching, the request is checked against its worst-case cost
            and rejected with 400 (`Insufficient max_price. Search requires
            max_price >= X for your query`) if the budget is too low. For
            example, 10 web results need `max_price >= 6.25`.
          minimum: 0
          exclusiveMinimum: true
          example: 20
        relevance_threshold:
          type: number
          description: >-
            Minimum relevance score (0.0-1.0) for results after reranking.
            Results below this threshold are filtered out.
          default: 0.5
          minimum: 0
          maximum: 1
          example: 0.5
        included_sources:
          type: array
          description: >-
            Sources to include in the search. Accepts:

            - Domain names or URLs for web filtering (e.g. `"arxiv.org"`,
            `"https://arxiv.org"`)

            - Dataset identifiers for proprietary sources (e.g.
            `"valyu/valyu-arxiv"`)

            - Preset names that expand to curated source groups: `"academic"`,
            `"finance"`, `"patent"`, `"transportation"`, `"politics"`,
            `"legal"`, `"health"`, `"genomics"`, `"chemistry"`, `"physics"`

            - `"web"` keyword to explicitly include web search alongside
            proprietary sources

            - `"collection:NAME"` to reference an org-scoped saved source
            collection


            With the default `scope_policy: "advisory"`, a list of two or more
            dataset IDs is treated as guidance: Valyu may search only the most
            relevant of them for the query. Set `scope_policy: "strict"` to
            search every listed dataset.


            Datasets above your plan are dropped; if none remain, the request
            returns 403 `tier_insufficient`. DeepResearch-only datasets are
            dropped when listed alongside other sources, and return 403 when
            they are the only sources requested.


            Note: most specialised and proprietary sources require a
            subscription. All plans include web search and open academic sources
            (arXiv, PubMed).
          items:
            type: string
          example:
            - valyu/valyu-arxiv
            - valyu/valyu-pubmed
        excluded_sources:
          type: array
          description: >-
            Sources to exclude from the search. Accepts domain names, URLs,
            dataset identifiers and preset names (e.g. `"finance"`,
            `"academic"`). Excluded datasets and presets are never searched.
            With `scope_policy: "strict"`, only dataset identifiers are
            accepted, and they are removed from the `included_sources` list.
          items:
            type: string
          example:
            - reddit.com
        scope_policy:
          type: string
          enum:
            - advisory
            - strict
          default: advisory
          description: >-
            How `included_sources` is applied to datasets.


            - `advisory` (default) - `included_sources` guides source selection.
            With two or more dataset IDs, Valyu may search only the most
            relevant of them.

            - `strict` - search exactly the dataset IDs in `included_sources`,
            minus any in `excluded_sources`. Requires 1-128 dataset IDs.
            Presets, domains, URLs, `"web"` and `search_type: "web"` are
            rejected, and web search is skipped. The response includes a
            `source_scope` receipt.


            Strict errors: 400 `invalid_scope_policy` (unknown value), 400
            `invalid_strict_source_scope` (missing, empty or oversized list, a
            non-dataset entry, or nothing left after exclusions), 400
            `unsupported_strict_source` (a dataset Search cannot serve), and 403
            `dataset_outside_task_scope` (a dataset outside your plan or grants;
            no partial fallback).


            Not yet in the Python or TypeScript SDKs. Send it in the request
            body over HTTP.
          example: strict
        source_biases:
          type: object
          description: >-
            Bias values for specific sources to influence ranking without hard
            filtering. Keys are domains (e.g., 'nasa.gov') or URL paths (e.g.,
            'nih.gov/research'). Values are integers from -5 (strong demotion)
            to +5 (strong boost). Most specific path match wins.
          additionalProperties:
            type: integer
            minimum: -5
            maximum: 5
          nullable: true
          example:
            nasa.gov: 5
            noaa.gov: 3
            nih.gov: 1
            example.com: -4
        instructions:
          type: string
          description: >-
            Natural language instructions to help rank results by relevance to
            user intent. Acts as a system prompt for the search. Max 500
            characters. Ignored when fast_mode is true.
          maxLength: 500
          example: Focus on oncology clinical trials from 2023 onwards
        category:
          type: string
          deprecated: true
          description: >-
            **Deprecated.** Use `instructions` instead. Falls back to this value
            if `instructions` is not set.
          maxLength: 500
        is_tool_call:
          type: boolean
          description: >-
            Indicates whether this request originates from an AI tool call.
            Affects query rewriting behavior.
          default: true
        response_length:
          description: |-
            Controls the maximum character length of content per result.

            - `"short"` - 25,000 characters (default)
            - `"medium"` - 50,000 characters
            - `"large"` - 100,000 characters
            - `"max"` - No limit
            - Any positive integer for a custom character limit
          oneOf:
            - type: string
              enum:
                - short
                - medium
                - large
                - max
            - type: integer
              minimum: 1
          default: short
          example: short
        start_date:
          type: string
          description: >-
            Filter results published on or after this date. Accepts `YYYY`,
            `YYYY-MM-DD` or an ISO-8601 datetime. Sub-day timestamps require
            `historical_cache: true`. If set without `end_date`, `end_date`
            defaults to today.
          example: '2024-01-01'
        end_date:
          type: string
          description: >-
            Filter results published on or before this date. Accepts `YYYY`,
            `YYYY-MM-DD` or an ISO-8601 datetime. Sub-day timestamps require
            `historical_cache: true`. If set without `start_date`, `start_date`
            defaults to `1900-01-01`. `start_date` must be on or before
            `end_date`.
          example: '2024-12-31'
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code for geo-targeted web search results.
          enum:
            - ALL
            - AR
            - AU
            - AT
            - BE
            - BR
            - CA
            - CL
            - DK
            - FI
            - FR
            - DE
            - HK
            - IN
            - ID
            - IT
            - JP
            - KR
            - MY
            - MX
            - NL
            - NZ
            - 'NO'
            - CN
            - PL
            - PT
            - PH
            - RU
            - SA
            - ZA
            - ES
            - SE
            - CH
            - TW
            - TR
            - GB
            - US
          example: US
        fast_mode:
          type: boolean
          description: >-
            Skip query rewriting and reranking for lower latency. Searches the
            web and financial data in parallel. Cannot be used with
            `search_type: "proprietary"`.
          default: false
        url_only:
          type: boolean
          description: >-
            Return only URLs without full content extraction. Only available
            when `search_type` is `"web"` or `"news"`. Skips reranking.
          default: false
        historical_cache:
          type: boolean
          description: >-
            Prefer cached content captured within the requested date window
            instead of the latest crawl. Requires a date range. With the default
            historical_cache_strict="prefer", a result can fall back to a live
            crawl when no suitable snapshot exists. Use "only" to drop results
            without a qualifying snapshot; neither mode guarantees complete
            historical coverage or reproduces an entire past search index.
          default: false
        historical_cache_strict:
          type: string
          enum:
            - 'off'
            - prefer
            - only
          description: >-
            Snapshot policy when historical_cache is true. "prefer" uses an
            in-window snapshot when available and otherwise may fall back to a
            live crawl. "only" drops results without a snapshot captured at or
            before the end-date cutoff. "off" disables strict snapshot
            filtering. Empty results are possible in every mode. For backtests,
            inspect record dates and snapshot evidence; publication-date filters
            alone do not establish point-in-time validity.
          default: prefer
        include_abstracts:
          type: boolean
          description: >-
            Expand PubMed search from papers with available full text to the
            complete abstract corpus. Results include the abstract and, when
            full text is available, the most relevant full-text chunks. Has no
            effect on other sources.
          default: false
        include_image_links:
          type: boolean
          description: >-
            Keep image URLs in the content. When `true` (default), images stay
            as markdown, for example `![Product
            photo](https://example.com/p.jpg)`. When `false`, each image becomes
            `[Image: Product photo]`. The API removes the image URL and keeps
            the alt text. The API removes an image with no alt text. A linked
            image `[![alt](src)](href)` becomes `[[Image: alt]](href)`. Other
            links do not change. Set `false` to use fewer tokens.
          default: true
        hls_coverage:
          type: string
          enum:
            - hls
            - increased_coverage
          default: hls
          description: >-
            Coverage for Wiley Health & Life Sciences (`wiley/wiley-hls`)
            searches. `hls` returns licensed Wiley content only.
            `increased_coverage` blends it with open-access biomedical
            literature in one ranked result set. See [Wiley
            HLS](https://docs.valyu.ai/guides/wiley-hls).
          example: hls
    SearchResponse:
      type: object
      description: Search response containing results and metadata.
      required:
        - success
        - tx_id
        - query
        - results
        - results_by_source
        - total_deduction_dollars
        - total_characters
      properties:
        success:
          type: boolean
          description: Whether the search completed successfully.
          example: true
        error:
          type: string
          nullable: true
          description: >-
            Error or warning message. May be non-empty even on successful
            responses if some sources had issues.
          example: null
        tx_id:
          type: string
          description: Transaction ID for tracking and support.
          example: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890
        query:
          type: string
          description: The original query as submitted.
          example: latest developments in quantum computing
        results:
          type: array
          description: Search results ordered by relevance.
          items:
            $ref: '#/components/schemas/SearchResult'
        results_by_source:
          type: object
          description: Count of results broken down by source type.
          properties:
            web:
              type: integer
              description: Number of web results.
              example: 5
            proprietary:
              type: integer
              description: Number of proprietary results.
              example: 3
          example:
            web: 1
            proprietary: 1
        total_deduction_dollars:
          type: number
          description: Total cost charged for this search.
          example: 0.0009375
        total_characters:
          type: integer
          description: Sum of all result content lengths in characters.
          example: 174
        warnings:
          type: array
          description: >-
            What the search skipped or adjusted, for example named datasets
            outside your plan. Present only when there is something to say. New
            warning types may be added at any time. See
            [Warnings](https://docs.valyu.ai/api-reference/warnings).
          items:
            $ref: '#/components/schemas/Warning'
        source_scope:
          type: object
          description: >-
            Receipt for a `scope_policy: "strict"` request. Present only for
            strict requests. It shows which datasets were dispatched and which
            returned rows. It does not certify full coverage: a dataset with no
            returned rows was not necessarily searched and found empty.
          properties:
            policy:
              type: string
              enum:
                - strict
              description: Scope policy applied.
            allowed_dataset_ids:
              type: array
              items:
                type: string
              description: Datasets in scope after exclusions.
            selected_dataset_ids:
              type: array
              items:
                type: string
              description: In-scope datasets the search was dispatched to.
            completed_dataset_ids:
              type: array
              items:
                type: string
              description: Datasets confirmed as fully searched. Currently always empty.
            returned_dataset_ids:
              type: array
              items:
                type: string
              description: Datasets that contributed at least one returned result.
            omitted_dataset_ids:
              type: array
              items:
                type: string
              description: In-scope datasets that were not dispatched.
            selection_basis:
              type: string
              description: How `selected_dataset_ids` was determined.
              example: dispatch_requested
            coverage:
              type: string
              description: Coverage claim. Currently always `unknown`.
              example: unknown
            exhaustive:
              type: boolean
              description: >-
                Whether the search is certified exhaustive. Currently always
                `false`.
              example: false
            errors:
              type: array
              description: One entry per dataset that failed during the search (max 32).
              items:
                type: object
                properties:
                  code:
                    type: string
                    example: source_execution_error
    Error:
      type: object
      description: >-
        Error response. Every error body has `error`. Search, Contents, Answer
        and Datasources errors usually also carry `success: false`. Errors
        returned before a request reaches the endpoint (missing, invalid or
        disabled keys, rate limits) and DeepResearch errors have no `success`
        field. Some errors add a machine-readable `code` and a `recovery`
        object.
      required:
        - error
      properties:
        success:
          type: boolean
          description: '`false` when present.'
          example: false
        error:
          type: string
          description: >-
            Error message, or a machine-readable code for some errors (for
            example `invalid_scope_policy`, or `rate_limited` on a `429`).
          example: Invalid request parameters
        message:
          type: string
          description: >-
            Human-readable detail. Present on errors returned before the request
            reaches the endpoint.
        code:
          type: string
          description: >-
            Stable machine-readable error code, when available. Branch on this
            rather than on the message text.
          example: insufficient_credits
        recovery:
          type: object
          description: Links or details that help resolve the error, when available.
          additionalProperties: true
        transaction_id:
          type: string
          description: Transaction ID for support, when available.
    SearchResult:
      type: object
      description: A single search result with extracted content.
      required:
        - id
        - title
        - url
        - content
        - source
        - price
        - length
        - data_type
        - source_type
      properties:
        id:
          type: string
          description: Unique identifier for this result (typically the URL).
          example: https://example.com/research/source-1
        title:
          type: string
          description: Title of the source document.
          example: Illustrative source document
        url:
          type: string
          format: uri
          description: URL of the source document.
          example: https://example.com/research/source-1
        content:
          type: string
          description: >-
            Extracted text content in markdown format, truncated to
            `response_length`.
          example: Placeholder content representing the text returned from a source.
        description:
          type: string
          nullable: true
          description: Short description or meta summary of the document.
          example: Illustrative metadata, not a factual research finding.
        source:
          type: string
          description: >-
            Source identifier. `"web"` for web results, or a proprietary source
            name.
          example: web
        price:
          type: number
          description: Cost charged for this individual result.
          example: 0.000625
        length:
          type: integer
          description: Character count of the `content` field.
          example: 65
        image_url:
          nullable: true
          description: >-
            Image URLs associated with this result, keyed by index. `null` if no
            images.
          oneOf:
            - type: object
              additionalProperties:
                type: string
                format: uri
            - type: string
              format: uri
          example:
            '0': https://example.com/images/source-image.png
        relevance_score:
          type: number
          description: Relevance score from reranking (0.0-1.0). Higher is more relevant.
          minimum: 0
          maximum: 1
          example: 0.92
        data_type:
          type: string
          description: Format of the content field.
          enum:
            - unstructured
            - structured
          example: unstructured
        source_type:
          type: string
          description: |-
            Classification of the source.

            - `website` - General web page
            - `forum` - Forum or discussion thread
            - `paper` - Academic paper
            - `data` - Structured data source
            - `report` - Report or analysis
            - `health_data` - Healthcare data
            - `clinical_trial` - Clinical trial record
            - `drug_label` - FDA drug label
            - `grants` - Research grant
          enum:
            - website
            - forum
            - paper
            - data
            - report
            - health_data
            - clinical_trial
            - drug_label
            - grants
          example: website
        publication_date:
          type: string
          description: Publication date in `YYYY-MM-DD` format, or empty string if unknown.
          example: '2024-06-15'
        crawl_date:
          type: string
          description: >-
            When the page was crawled (web results). With `historical_cache`, it
            is second-precision and never later than the `end_date` cutoff.
          example: '2024-06-16T08:12:45Z'
        abstract:
          type: string
          description: Document-level abstract for academic results when available.
          example: >-
            Placeholder abstract; the actual abstract depends on the returned
            paper.
        doi:
          type: string
          description: DOI identifier (academic results only).
        citation:
          type: string
          description: Citation text (academic results only).
          example: ''
        citation_count:
          type: integer
          description: Number of citations (academic results only).
        authors:
          type: array
          description: Author names (academic results only).
          items:
            type: string
        references:
          type: string
          description: References text (academic results only).
          example: ''
        metadata:
          type: object
          description: >-
            Additional structured metadata (financial and specialized results
            only).
          additionalProperties: true
    Warning:
      type: object
      description: >-
        Something the request skipped or adjusted. A warning means the request
        succeeded. New `type` values may be added at any time, so handle unknown
        ones by showing `message`. See
        [Warnings](https://docs.valyu.ai/api-reference/warnings).
      required:
        - type
        - message
      properties:
        type:
          type: string
          description: >-
            Stable snake_case warning type, for example `datasets_not_in_plan`.
            New types may be added at any time.
          example: datasets_not_in_plan
        message:
          type: string
          description: >-
            Self-contained sentence, safe to show a user or for an agent to
            relay as-is.
          example: >-
            Your Pay-as-you-go plan doesn't include valyu/valyu-chemrxiv
            (Comfortably Pro, $99/mo), so it was skipped. Results come from your
            other sources. Comfortably Pro ($99/mo) includes it:
            https://platform.valyu.ai/user/account/billing?tab=plan
        detail:
          type: object
          nullable: true
          description: Optional type-specific structured fields, including any URLs.
          additionalProperties: true
          example:
            datasets:
              - id: valyu/valyu-chemrxiv
                required_plan: tier_2
            current_plan: tier_0
            required_plan:
              id: tier_2
              name: Comfortably Pro
              price: $99/mo
            upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
  responses:
    Unauthorized:
      description: Missing or invalid API key. Send your key in the `X-API-Key` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_or_invalid:
              summary: Missing or invalid API key
              value:
                error: Unauthorized
                message: API key is missing or invalid
            invalid_key:
              summary: Invalid API key (endpoint response)
              value:
                success: false
                error: Invalid API key
    PaymentRequired:
      description: >-
        The request can't be paid for. Nothing is charged.


        `code` tells you why:

        - `insufficient_credits` - the balance is used up. Top up, or wait for
        your plan's monthly allowance to renew.

        - `credit_limit_reached` - the organisation's optional monthly usage
        limit is reached. Raise the limit in the dashboard.

        - `spend_cap_reached` - this API key's budget cap is reached. Raise the
        key's cap or use another key.


        Search, Contents and Answer return the body shown in the examples.
        `error` is a sentence you can relay that ends with the link that fixes
        it, and `recovery` repeats the links. Below the top self-serve plan,
        `insufficient_credits` also carries `upgrade_url`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            insufficient_credits:
              summary: Balance exhausted
              value:
                success: false
                error: >-
                  Your credit balance is used up. Nothing was charged. Top up to
                  continue:
                  https://platform.valyu.ai/user/account/billing?tab=credits
                  Monthly plans give you cheaper credits and more data sources:
                  https://platform.valyu.ai/user/account/billing?tab=plan
                code: insufficient_credits
                recovery:
                  topup_url: https://platform.valyu.ai/user/account/billing?tab=credits
                  topup_api: POST https://api.valyu.ai/v1/account/balance/topup
                  upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
                transaction_id: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890
            credit_limit_reached:
              summary: Monthly usage limit reached
              value:
                success: false
                error: >-
                  Your organisation's monthly credit limit is reached. Nothing
                  was charged. Raise the limit to continue:
                  https://platform.valyu.ai/user/account/billing?tab=credits
                code: credit_limit_reached
                recovery:
                  increase_limit_url: https://platform.valyu.ai/user/account/billing?tab=credits
                transaction_id: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890
            spend_cap_reached:
              summary: API key budget cap reached
              value:
                success: false
                error: >-
                  This API key has reached its credit cap. Nothing was charged.
                  Raise the key's cap or use an uncapped key:
                  https://platform.valyu.ai/user/account/apikeys
                code: spend_cap_reached
                recovery:
                  increase_cap_url: https://platform.valyu.ai/user/account/apikeys
                transaction_id: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890
    RateLimited:
      description: >-
        Over this endpoint's rate limit for your plan. Nothing is charged. Wait
        `retry_after` seconds (the `Retry-After` header), then retry with
        backoff. See [Rate
        limits](https://docs.valyu.ai/api-reference/overview#rate-limits).


        `message` is a sentence you can relay that names the limit and how to
        raise it. `error` and `code` are both `rate_limited`, and `recovery`
        repeats `retry_after`, `plan`, `limit` and `upgrade_url` (`contact_url`
        on the top plans), which also stay at the top level.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rate_limited:
              summary: Search rate limit reached
              value:
                error: rate_limited
                code: rate_limited
                message: >-
                  Search rate limit reached: your Pay-as-you-go plan allows 5
                  requests per second. Retry after 2 seconds. Upgrade to
                  Ridiculously Cheap for 10 requests per second:
                  https://platform.valyu.ai/user/account/billing?tab=plan
                retry_after: 2
                plan: Pay-as-you-go
                limit:
                  endpoint: search
                  requests_per_second: 5
                upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
                recovery:
                  retry_after: 2
                  upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
                  plan: Pay-as-you-go
                  limit:
                    endpoint: search
                    requests_per_second: 5
    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            example:
              summary: Internal error
              value:
                success: false
                error: Internal server error. Please try again later.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get yours at
        [platform.valyu.ai](https://platform.valyu.ai).

````

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