Skip to main content
POST
/
v1
/
deepsearch
curl --request POST \
  --url https://api.valyu.network/v1/deepsearch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "query": "latest developments in quantum computing"
}'
{
  "success": true,
  "error": null,
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "results": [
    {
      "title": "Quantum Computing Breakthrough: New Error Correction Method",
      "url": "https://nature.com/articles/quantum-error-correction-2024?utm_source=valyu",
      "content": "Researchers at MIT have developed a revolutionary quantum error correction method that reduces error rates by 90% while maintaining computational speed. This breakthrough addresses one of the fundamental challenges in scaling quantum computers...",
      "description": "Major breakthrough in quantum error correction methodology",
      "source": "academic",
      "price": 0.005,
      "length": 15420,
      "data_type": "unstructured",
      "source_type": "paper",
      "publication_date": "2024-03-15",
      "id": "https://nature.com/articles/quantum-error-correction-2024",
      "image_url": {
        "main": "https://nature.com/quantum-diagram.jpg"
      }
    },
    {
      "title": "IBM Announces 1000-Qubit Quantum Processor",
      "url": "https://techcrunch.com/2024/05/12/ibm-quantum-1000-qubit?utm_source=valyu",
      "content": "IBM has unveiled its latest quantum processor featuring over 1000 qubits, marking a significant milestone in quantum computing hardware development. The new processor, called Condor, demonstrates improved coherence times and reduced error rates...",
      "description": "IBM's latest quantum hardware milestone announcement",
      "source": "web",
      "price": 0.003,
      "length": 8950,
      "data_type": "unstructured",
      "source_type": "website",
      "publication_date": "2024-05-12",
      "id": "https://techcrunch.com/2024/05/12/ibm-quantum-1000-qubit",
      "image_url": {
        "main": "https://techcrunch.com/ibm-quantum-chip.jpg"
      }
    }
  ],
  "total_results": 25,
  "results_returned": 2,
  "total_cost_dollars": 0.008,
  "total_characters": 24370
}

Authorizations

​
x-api-key
string
header
required

Your Valyu API key. Get one at platform.valyu.network

Body

application/json

Search parameters for context retrieval

​
query
string
required

The query string for the search

Example:

"implementation of agentic search-enhanced large reasoning models"

​
max_num_results
integer
default:5

Maximum number of results to return (1-20)

Required range: 1 <= x <= 20
Example:

10

​
search_type
enum<string>
default:all

Type of search to perform. 'proprietary' uses Valyu's full-text multimodal indicies (arxiv/pubmed/proprietary academic content).

Available options:
all,
web,
proprietary
Example:

"all"

​
fast_mode
boolean
default:false

Enable fast mode for reduced latency but shorter results. Best for general purpose queries.

Example:

true

​
max_price
number
default:20

Maximum price in dollars for a thousand retrievals (CPM)

Required range: x >= 0
Example:

30

​
relevance_threshold
number
default:0.5

Minimum relevance score for results (0.0-1.0)

Required range: 0 <= x <= 1
Example:

0.5

​
included_sources
string[]

List of specific sources to search (URLs, domains or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.network/blog' or 'valyu.network/blog'), only that specific path will be searched. For entire domains, use either the domain name (e.g., 'valyu.network') or the base URL (e.g., 'https://valyu.network').

Example:
[
  "https://docs.aws.amazon.com/",
  "techcrunch.com/news",
  "valyu/valyu-arxiv"
]
​
excluded_sources
string[]

List of specific sources to exclude from search (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.network/blog' or 'valyu.network/blog'), only that specific path will be excluded. For entire domains, use either the domain name (e.g., 'valyu.network') or the base URL (e.g., 'https://valyu.network').

Example:
[
  "https://news.ycombinator.com/",
  "github.com/valyu",
  "valyu/valyu-pubmed"
]
​
category
string | null

Natural language category/guide phrase to help guide the search to the most relevant content. For example 'agentic use-cases

Example:

"agentic use-cases"

​
response_length
default:short

Controls the length of content returned per result. Can be an integer for character count or predefined values: 'short' (25k), 'medium' (50k), 'large' (100k), 'max' (full) Maximum number of characters to return per result

Required range: x >= 1
Example:

"short"

​
country_code
string | null

2-letter ISO country code to bias search results to a specific country

Example:

"US"

​
is_tool_call
boolean
default:true

Tunes retrieval process based on whether the API is being called by an AI agent as a tool call, or a user query.

Example:

false

​
start_date
string<date> | null

Start date for time-filtered searches (YYYY-MM-DD)

Example:

"2024-01-01"

​
end_date
string<date> | null

End date for time-filtered searches (YYYY-MM-DD)

Example:

"2024-12-31"

Response

Successful response with search results

​
success
boolean
required

Whether the request was successful

Example:

true

​
error
string
required

Error message (empty if successful). Will show reason for failure or if there are an recommendations to improve the search results (e.g. 'max price too low, 5 results removed') - this can be fed to agents to assist in autonomous agentic workflows

Example:

""

​
tx_id
string
required

Unique transaction ID for this request

Example:

"tx_12345678-1234-1234-1234-123456789abc"

​
query
string
required

The query string for the search

Example:

"implementation of agentic search-enhanced large reasoning models"

​
results
object[]
required

Array of search result objects. The results are sorted by relevance.

​
results_by_source
object
required

Count of results by source type

​
total_deduction_pcm
number
required

Total cost in cost per mille

Example:

150

​
total_deduction_dollars
number
required

Total cost in dollars

Example:

0.15

​
total_characters
integer
required

Total character count of all results

Example:

12500

⌘I