POST
/
v1
/
deepsearch
Search and retrieve relevant context based on a query
curl --request POST \
  --url https://api.valyu.network/v1/deepsearch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "query": "implementation of agentic search-enhanced large reasoning models",
  "max_num_results": 10,
  "search_type": "all",
  "max_price": 30,
  "relevance_threshold": 0.5,
  "included_sources": [
    "https://docs.aws.amazon.com/",
    "techcrunch.com/news",
    "valyu/valyu-arxiv"
  ],
  "excluded_sources": [
    "https://news.ycombinator.com/",
    "github.com/valyu",
    "valyu/valyu-pubmed"
  ],
  "category": "agentic use-cases",
  "response_length": "short",
  "country_code": "US",
  "is_tool_call": false,
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}'
{
  "success": true,
  "error": "",
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "query": "implementation of agentic search-enhanced large reasoning models",
  "results": [
    {
      "id": "unique_result_id",
      "title": "Breakthrough in Quantum Computing Architecture",
      "url": "https://example.com/article?utm_source=valyu.network&utm_medium=referral&utm_campaign=ai_pilot&utm_content=ai_query",
      "content": "Detailed article content about quantum computing developments...",
      "source": "web",
      "length": 1250,
      "image_url": "https://example.com/image.jpg",
      "publication_date": "2024-03-15",
      "doi": "10.1000/example",
      "citation": "Author et al. (2024)",
      "citation_count": 42,
      "authors": [
        "Dr. Jane Smith",
        "Dr. John Doe"
      ],
      "references": "Reference information",
      "price": 0.015,
      "data_type": "unstructured",
      "source_type": "website"
    }
  ],
  "results_by_source": {
    "web": 5,
    "proprietary": 3
  },
  "total_deduction_pcm": 150,
  "total_deduction_dollars": 0.15,
  "total_characters": 12500
}

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"

​
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