Search API reference - POST /v1/search

curl --request POST \
  --url https://api.valyu.ai/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "latest developments in quantum computing",
  "max_num_results": 5
}
'

{
  "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
}

POST

curl --request POST \
  --url https://api.valyu.ai/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "latest developments in quantum computing",
  "max_num_results": 5
}
'

{
  "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
}

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

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". site: and -site: operators in the query filter every result, web and dataset alike. Check available sources 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.

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. 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. See pricing. Start with a specific question and five results, then adjust source filters and result length against representative tasks. Use DeepResearch when you want to run the investigation and receive a report.

Authorizations

X-API-Key

string

header

required

API key for authentication. Get yours at platform.valyu.ai.

Body

application/json

Search request parameters.

query

string

required

The search query to execute. Supports natural language queries.

Example:

"latest developments in quantum computing"

max_num_results

integer

default:5

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.

Required range: 1 <= x <= 20

Example:

10

search_type

enum<string>

default:all

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.

Available options:

all,

web,

proprietary,

news

Example:

"all"

max_price

number

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.

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.

Required range: x > 0

Example:

20

relevance_threshold

number

default:0.5

Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out.

Required range: 0 <= x <= 1

Example:

0.5

included_sources

string[]

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

Example:

["valyu/valyu-arxiv", "valyu/valyu-pubmed"]

excluded_sources

string[]

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.

Example:

["reddit.com"]

scope_policy

enum<string>

default:advisory

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.

Available options:

advisory,

strict

Example:

"strict"

source_biases

object | null

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.

Show child attributes

Example:

{
  "nasa.gov": 5,
  "noaa.gov": 3,
  "nih.gov": 1,
  "example.com": -4
}

instructions

string

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.

Maximum string length: 500

Example:

"Focus on oncology clinical trials from 2023 onwards"

Response

Search completed successfully with results.

Search response containing results and metadata.

success

boolean

required

Whether the search completed successfully.

Example:

true

tx_id

string

required

Transaction ID for tracking and support.

Example:

"tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

query

string

required

The original query as submitted.

Example:

"latest developments in quantum computing"

results

object[]

required

Search results ordered by relevance.

Show child attributes

results_by_source

object

required

Count of results broken down by source type.

Show child attributes

Example:

{ "web": 1, "proprietary": 1 }

total_deduction_dollars

number

required

Total cost charged for this search.

Example:

0.0009375

total_characters

integer

required

Sum of all result content lengths in characters.

Example:

174

error

string | null

Error or warning message. May be non-empty even on successful responses if some sources had issues.

Example:

null

warnings

object[]

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.

Show child attributes

source_scope

object

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.

Show child attributes

API essentials

Search

Contents

Answer

DeepResearch

DeepResearch (Batch)

Workflows

Datasources

Search

Choose the source boundary

Remove image links

Use the results

Authorizations

Body

Response

​Choose the source boundary

​Remove image links

​Use the results

Authorizations

Body

Response

Choose the source boundary

Remove image links

Use the results