The Valyu SDK provides access to the following features:

  1. Deep Search - Search and retrieve relevant content from proprietary and public sources

​
Getting Started

Install the Valyu SDK

pip install valyu

And then instantiate the Valyu client - you can obtain your API key here ($10 free credits cus we are legends)

from valyu import Valyu

# The SDK will automatically use VALYU_API_KEY from environment
valyu = Valyu()

# Alternatively, you can still pass it explicitly
valyu = Valyu(api_key="your-api-key-here")

​
Quick Start

Let’s see how to use the deep search feature with a simple example:

main.py
from valyu import Valyu

# Initialize the client
valyu = Valyu()

# Search for information about a specific topic
response = valyu.search(
    "What are the benefits of renewable energy?",
    search_type="all",            # Search both proprietary and web sources
    max_num_results=5,            # Limit to top 5 results
    relevance_threshold=0.5,      # Only return results with >50% relevance
    max_price=30.0,               # Maximum cost in dollars
    is_tool_call=True             # True for AI agents/tools, False for direct user queries
)

# Process the results
print(response)

​
Advanced Usage

Here’s an example using more v2 parameters for targeted searches:

# AI Agent making a search (tool call)
financial_response = valyu.search(
    "Pfizer stock price since COVID-19 outbreak",
    search_type="proprietary",
    max_num_results=1,
    relevance_threshold=0.5,
    max_price=30.0,
    is_tool_call=True  # True: AI agent/tool is making this search
)

# Direct user query (not through an AI agent)
user_response = valyu.search(
    "What are the latest developments in quantum computing?",
    search_type="all",
    max_num_results=5,
    relevance_threshold=0.5,
    max_price=30.0,
    is_tool_call=False  # False: Direct user query, not through AI agent
)

# Academic research with specific sources (AI agent)
academic_response = valyu.search(
    "CRISPR gene editing safety studies",
    search_type="proprietary",
    max_num_results=8,
    relevance_threshold=0.6,
    max_price=30.0,
    category="biomedical research",
    included_sources=["valyu/valyu-pubmed"],
    is_tool_call=True  # True: Part of an AI agent workflow
)

​
Input Parameters:

ParameterTypeDescriptionDefault
querystrThe input query to be processed.Required
search_typeLiteral[‘all’, ‘proprietary’, ‘web’]Specifies the type of search to be performed. ‘all’ includes both proprietary and web sources, ‘proprietary’ searches over Valyu indices, and ‘web’ is just web search.”all”
max_num_resultsintThe maximum number of results to be returned (1-20).5
relevance_thresholdfloatThe minimum relevance score required for a result to be included (0.0-1.0).0.5
max_pricefloatMaximum cost in dollars for 1000 retrievals.30.0
is_tool_callboolSet to True when called by AI agents/tools (optimized for LLM consumption). Set to False for direct user queries.True
categorystrNatural language category to guide search context (optional).None
included_sourcesList[str]List of specific datasets or URLs to search within (optional).None
start_datestrStart date for time filtering in YYYY-MM-DD format (optional).None
end_datestrEnd date for time filtering in YYYY-MM-DD format (optional).None

​
Example Response:

{
    "success": True,
    "error": "",
    "tx_id": "tx_4cce8eed-7864-42ec-b385-dee7d5b14936",
    "query": "What are agentic search-enhanced large reasoning models?",
    "results": [
        {
            "title": "2501.05366",
            "url": "https://arxiv.org/abs/2501.05366",
            "content": "# Search-o1: Agentic Search-Enhanced Large Reasoning Models...",
            "source": "valyu/valyu-arxiv",
            "price": 0.0005,
            "length": 17442,
            "image_url": {
                "_page_1_Figure_0.jpeg": "https://..."
            },
            "data_type": "unstructured",
            "relevance_score": 0.77734375
        }
        // Additional results...
    ],
    "results_by_source": {
        "web": 1,
        "proprietary": 4
    },
    "total_results": 5,
    "total_characters": 81208
}

​
Output Parameters:

ParameterTypeDescription
successbooleanIndicates if the request was successful
errorstringError message if any
tx_idstringUnique transaction ID for the request
querystringThe processed query string
resultsarrayArray of result objects (see Results Object table below)
results_by_sourceobjectCount of results by source type (web/proprietary)
total_resultsintegerTotal number of results returned
total_charactersintegerTotal number of characters in results

​
Results Object:

ParameterTypeDescription
idstringUnique identifier for the result (optional)
titlestringTitle of the result
urlstringURL of the source
contentstringThe actual text chunk of the result
sourcestringSource identifier (e.g., “valyu/valyu-arxiv”, “valyu/valyu-stocks-US”)
pricefloatCost of this specific text chunk in USD
lengthintegerCharacter length of the content
image_urlobjectMap of image identifiers to image URLs, can be used to render in frontend AI applications
data_typestringType of data, either “unstructured” or “structured”. If structured (e.g. for stock data) it will be a string JSON object
source_typestringType of source (e.g., “paper”, “data”, “web”, “book”)
relevance_scorefloatRelevance score between 0 and 1
publication_datestringPublication date in YYYY-MM-DD format (for source_type “paper” and “book”)
doistringDigital Object Identifier (for source_type “paper” and “book”)
citationstringFormatted citation string (for source_type “paper”)
citation_countintegerNumber of citations (for source_type “paper”)
authorsarrayList of author names (for source_type “paper” and “book”)
referencesstringReferences section content (for source_type “paper” and “book”)