Rust SDK: Search

Search the web, SEC filings, papers, clinical trials and other datasets from Rust with the Valyu SDK. Filter sources and dates, control size and cost.

The Rust SDK is in alpha. Interfaces may change between releases; check the crate version before upgrading.

Retrieve relevant content and source URLs across the web and specialist datasets. Use the results in your own application, model or research loop.

Basic usage

use valyu::ValyuClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ValyuClient::new(std::env::var("VALYU_API_KEY")?);

    let response = client.search("How do public companies describe supply chain concentration risks?").await?;

    if let Some(results) = &response.results {
        for result in results {
            println!("{} - {}",
                result.title.as_deref().unwrap_or("Untitled"),
                result.url.as_deref().unwrap_or("No URL"));
        }
    }

    Ok(())
}

Common patterns

Use the DeepSearchRequest builder for anything beyond a plain query, then call client.deep_search(&request):

use valyu::DeepSearchRequest;

// Fast mode - lower latency, shorter content
let req = DeepSearchRequest::new("quantum computing").with_fast_mode(true);

// Restrict to specific sources (datasets, domains, or presets)
let req = DeepSearchRequest::new("quantum computing applications")
    .with_included_sources(vec![
        "valyu/valyu-arxiv".to_string(),
        "valyu/valyu-pubmed".to_string(),
    ])
    .with_response_length("medium");
// ...or exclude sources instead (use one or the other, not both)
let req = DeepSearchRequest::new(query)
    .with_excluded_sources(vec!["example.com".to_string()]);

// Filter by country and date range
let req = DeepSearchRequest::new("renewable energy policies")
    .with_country_code("US")
    .with_date_range("2024-01-01", "2024-12-31");

let response = client.deep_search(&req).await?;
println!("Cost: {:.4}", response.total_deduction_dollars.unwrap_or(0.0));

Building a multi-step research flow on top of Search? Consider DeepResearch to combine search, analysis and report generation. Keep Search when you need to control each retrieval.

Reference

Builder methods

query (impl Into<String>, required) - the search query. See the Prompting Guide.

Method	Type	Description	Default
with_search_type()	"web" | "proprietary" | "all"	Which sources to search	"all"
with_max_results()	u8	Results to return (1-20)	10
with_max_price()	f64	Cap on the cost of the whole request. See pricing	None
with_is_tool_call()	bool	true for AI agents/tools	true
with_relevance_threshold()	f64	Minimum relevance score (0.0-1.0)	0.5
with_included_sources()	Vec<String>	Sources to search within	None
with_excluded_sources()	Vec<String>	Sources to exclude	None
with_category()	impl Into<String>	Natural-language category to guide search	None
with_date_range()	(start, end)	Date filter (YYYY-MM-DD)	None
with_country_code()	impl Into<String>	2-letter ISO country code to bias results	None
with_response_length()	impl Into<String>	"short", "medium", "large", or "max"	"short"
with_fast_mode()	bool	Reduced latency	false

Response format

pub struct SearchResponse {
    pub success: bool,
    pub error: Option<String>,
    pub tx_id: Option<String>,
    pub query: Option<String>,
    pub results: Option<Vec<SearchResult>>,
    pub results_by_source: Option<ResultsBySource>,
    pub total_deduction_dollars: Option<f64>,
    pub total_characters: Option<i32>,
}

pub struct SearchResult {
    pub title: Option<String>,
    pub url: Option<String>,
    pub content: Option<String>,
    pub description: Option<String>,
    pub source: Option<String>,
    pub price: Option<f64>,
    pub length: Option<i32>,
    pub relevance_score: Option<f64>,
    pub data_type: Option<String>,
    // Academic sources also populate:
    pub publication_date: Option<String>,
    pub authors: Option<Vec<String>>,
    pub citation: Option<String>,
    pub doi: Option<String>,
    // ... other optional fields
}

Error handling

use valyu::{DeepSearchRequest, ValyuError};

match client.deep_search(&DeepSearchRequest::new("test query")).await {
    Ok(response) => {
        if !response.success {
            eprintln!("Search failed: {:?}", response.error);
            return;
        }
        if let Some(results) = &response.results {
            for result in results {
                println!("{} ({:.2})",
                    result.title.as_deref().unwrap_or("Untitled"),
                    result.relevance_score.unwrap_or(0.0));
            }
        }
    }
    Err(ValyuError::InvalidApiKey) => eprintln!("Invalid API key"),
    Err(ValyuError::RateLimitExceeded) => eprintln!("Rate limit exceeded"),
    Err(e) => eprintln!("Error: {}", e),
}

Source types

• Web - general websites, news, blogs, forums, documentation.
• Specialist indexes (proprietary in the API) - Includes open and licensed sources. For example, valyu/valyu-arxiv (arXiv papers), valyu/valyu-pubmed (medical literature), valyu/valyu-stocks (market data), and many more.

Browse the full catalog on the Valyu Platform.