Search Quickstart

Search web content, academic journals, financial data, and proprietary datasets in one API call. Results come back ranked and ready for RAG pipelines and AI agents.

Make your first call

pip install valyu   # or: npm install valyu-js
export VALYU_API_KEY=your_key   # get one at https://platform.valyu.ai

from valyu import Valyu

valyu = Valyu()  # reads VALYU_API_KEY from env

response = valyu.search(
    query="latest developments in quantum computing",
    max_num_results=5,
    search_type="all",
)

for result in response["results"]:
    print(result["title"], result["url"])
    print(result["content"][:200])

import { Valyu } from "valyu-js";

const valyu = new Valyu(); // reads VALYU_API_KEY from env

const response = await valyu.search({
  query: "latest developments in quantum computing",
  maxNumResults: 5,
  searchType: "all",
});

response.results.forEach((result) => {
  console.log(result.title, result.url);
  console.log(result.content.substring(0, 200));
});

curl -X POST https://api.valyu.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "latest developments in quantum computing",
    "max_num_results": 5,
    "search_type": "all"
  }'

Pass a natural-language query (no site:, AND, OR, or quotes - Valyu is semantic, not keyword). Read total_deduction_dollars from the response to track spend.

Search types

Type	Searches	Use for
`all`	Web + proprietary (default)	Comprehensive coverage
`web`	Web only	Current events, general topics
`proprietary`	Research, financial, premium sources	Research, technical analysis
`news`	News articles only	Current news and journalism

Drop Search into your agent

Hand this prompt to your coding agent (Cursor, Claude Code, Copilot) to wire up Search end to end.

Integrate Valyu Search into your AI agent, with guidance on when to escalate to DeepResearch and which sources need a plan.

Open in Cursor

Doing multi-step research or knowledge work? DeepResearch is an autonomous agent built on this same engine that plans, searches, verifies, and writes a cited report - often cheaper than orchestrating Search yourself.

Common parameters

The essentials you’ll reach for most. See the full parameter reference below for everything else.

Parameter	Default	What it does
`query`	-	Natural-language query (required)
`search_type`	`all`	`all`, `web`, `proprietary`, or `news`
`max_num_results`	`5`	Results to return (1-20; up to 100 with the `increased_max_results` permission)
`response_length`	`short`	Content per result: `short`, `medium`, `large`, `max`, or a char count
`relevance_threshold`	`0.5`	Drop matches below this score (0-1)
`included_sources`	`[]`	Restrict to datasets, domains, presets, or `collection:<name>`
`max_price`	`1000`	Cost ceiling per 1k results (CPM)

Filtering

Sources

Include, exclude, or soft-rank domains and datasets.

Dates

Filter by publication date.

Collections

Save reusable source bundles.

All parameters

SDK arguments use camelCase in TypeScript (maxNumResults) and snake_case in Python (max_num_results).

Full parameter reference

query

string

required

Natural-language search query. Use semantic phrasing, not operators (no site:, AND, OR, or quotes).

max_num_results

integer

default:"5"

Number of results to return. 1-20 by default; up to 100 with the increased_max_results permission on your API key.

search_type

string

default:"all"

all (web + proprietary), web, proprietary, or news.

relevance_threshold

number

default:"0.5"

Minimum relevance score (0-1). Results below the threshold are dropped. Raise it for precision, lower it for recall.

max_price

number

default:"1000"

Maximum price per thousand results (CPM) you are willing to pay. Acts as a cost ceiling. Web search is ~$1.50/1k, proprietary ~$0.50/1k.

included_sources

string[]

default:"[]"

Restrict the search to these sources. Accepts dataset ids (valyu/valyu-arxiv), domains/URLs (arxiv.org), presets (academic, finance, patent, …), collections (collection:<name>), or the keyword web.

excluded_sources

string[]

default:"[]"

Exclude these sources. Same formats as included_sources. If both are set, included_sources wins.

source_biases

object

default:"{}"

Soft-rank sources without hard filtering. Map each source to an integer from -5 (strong demotion) to +5 (strong boost); 0 is neutral.

response_length

string | integer

default:"short"

Content returned per result: short (~25k chars), medium (~50k), large (~100k), max (full content), or an exact integer character count.

category

string

Natural-language category hint to steer ranking (e.g. "machine learning"). Max 500 characters.

instructions

string

Free-text instructions that guide how results are selected and ranked. Max 500 characters.

start_date

string

Include content published on or after this date. Format YYYY-MM-DD.

end_date

string

Include content published on or before this date. Format YYYY-MM-DD.

country_code

string

ISO 3166-1 alpha-2 country code to bias results toward a region (e.g. "GB", "US"). Use ALL for no preference.

is_tool_call

boolean

default:"true"

true optimises results for LLM consumption (the default for agents); false optimises for human reading.

fast_mode

boolean

default:"false"

Lower-latency responses with shorter content. Cannot be combined with search_type="proprietary".

url_only

boolean

default:"false"

Return URLs and metadata without extracting full content. Only valid with search_type="web" or "news".

historical_cache

boolean

default:"false"

Allow results to be served from the historical cache where available.

Fast mode (lower latency)

Returns quicker responses with shorter content. Good for general queries. Cannot be combined with search_type="proprietary".

response = valyu.search(
    query="latest market trends in tech stocks",
    fast_mode=True,
    max_num_results=5,
)

const response = await valyu.search({
  query: "latest market trends in tech stocks",
  fastMode: true,
  maxNumResults: 5,
});

Returning up to 100 results

The default maximum is 20 results per query. To return up to 100, request the increased_max_results permission:

Go to API Key Management
Request the increased_max_results permission
Create a new API key after approval

Python

response = valyu.search(
    query="renewable energy innovations 2025",
    max_num_results=100,  # requires increased_max_results permission
)

Error handling

Python

from valyu import Valyu

valyu = Valyu()

try:
    response = valyu.search(query="quantum computing applications", max_num_results=10)
    if response.get("success"):
        for result in response["results"]:
            print(result["title"], result["source_type"])
    else:
        print(f"Search failed: {response.get('error', 'Unknown error')}")
except Exception as e:
    print(f"Request failed: {e}")

Response format

{
  "success": true,
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "query": "latest developments in quantum computing",
  "results": [
    {
      "title": "Quantum Computing Breakthrough: New Error Correction Method",
      "url": "https://arxiv.org/abs/2024.12345?utm_source=valyu",
      "content": "Researchers at MIT have developed a quantum error correction method...",
      "description": "Major breakthrough in quantum error correction methodology",
      "source": "academic",
      "price": 0.005,
      "length": 15420,
      "source_type": "paper",
      "publication_date": "2024-03-15",
      "relevance_score": 0.94
    }
  ],
  "results_by_source": { "web": 0, "proprietary": 1 },
  "total_deduction_dollars": 0.008,
  "total_characters": 24370
}

Top-level fields

Field	Description
`success`	Whether the search completed successfully
`error`	Empty on success; error message otherwise
`tx_id`	Transaction ID for tracing and support
`query`	The processed search query
`results`	Array of result objects, ranked by relevance
`results_by_source`	Result counts split into web vs proprietary
`total_deduction_dollars`	Total cost in USD
`total_characters`	Total characters across results

Result fields

Field	Description
`title`	Document or article title
`url`	Canonical URL (may include tracking parameters)
`content`	Extracted text, trimmed per `response_length`
`description`	Brief summary
`source`	Source category: `web`, `academic`, etc.
`price`	Cost in USD for this result
`length`	Character count
`source_type`	Specific source classification (see below)
`publication_date`	ISO 8601 date when available
`relevance_score`	Score between 0 and 1
`image_url`	Extracted images
`doi`, `authors`, `citation`, `citation_count`, `references`	Academic results only
`metadata`	Additional structured metadata (financial/specialized)

Source types

Type	Description
`general`	General knowledge (e.g., Wikipedia)
`website`	General web pages
`forum`	Forums and Q&A sites
`paper`	Academic papers (arXiv, etc.)
`data`	Market data and analytics
`report`	SEC regulatory filings
`health_data`	Global health indicators
`clinical_trial`	Clinical trial summaries from ClinicalTrials.gov
`drug_label`	FDA drug labels from DailyMed
`grants`	NIH funding data

Next steps

Prompting guide

Write queries that get better results

Tips & tricks

Optimise performance and control costs

API reference

Complete parameter documentation

Data sources

Every source you can target

​Make your first call

​Search types

​Drop Search into your agent

​Common parameters

​Filtering

Sources

Dates

Collections

​All parameters

​Response format

​Next steps

Prompting guide

Tips & tricks

API reference

Data sources

Make your first call

Search types

Drop Search into your agent

Common parameters

Filtering

All parameters

Response format

Next steps