valyu 2.8.9

Deepsearch API for AI.

Valyu Python SDK

Search and research APIs built for AI agents. Access web and proprietary data sources through Search, extract content from URLs, generate grounded answers, and run multi-step research with DeepResearch - all through a single SDK.

Documentation | API Reference | Platform

Installation

pip install valyu

Quick Start

from valyu import Valyu

valyu = Valyu()  # uses VALYU_API_KEY env var

response = valyu.search(
    "latest advances in transformer architectures",
    max_num_results=5,
    search_type="all",
)

for result in response.results:
    print(result.title, result.url)

Get $10 free credits when you sign up at platform.valyu.ai. No credit card required.

APIs

Search

Search across web and proprietary data sources with a single query.

response = valyu.search(
    "CRISPR gene therapy clinical trials 2026",
    search_type="proprietary",                     # "all", "web", or "proprietary"
    max_num_results=10,                            # 1-20 results
    included_sources=["valyu/valyu-pubmed"],        # filter to specific sources
    start_date="2026-01-01",                       # date filtering
    end_date="2026-12-31",
)

All search parameters

Parameter	Type	Default	Description
query	str	required	Search query
search_type	str	"all"	"all", "web", or "proprietary"
max_num_results	int	10	Results to return (1-20)
max_price	int	30	Max price per thousand queries (CPM)
relevance_threshold	float	0.5	Min relevance score (0-1)
included_sources	List[str]	None	Sources to search
excluded_sources	List[str]	None	Sources to exclude
start_date	str	None	Start date (YYYY-MM-DD)
end_date	str	None	End date (YYYY-MM-DD)
country_code	str	None	Country filter (e.g. "US", "GB")
response_length	str | int	None	"short", "medium", "large", "max", or character count
category	str	None	Category filter
fast_mode	bool	False	Faster results, shorter content

Contents

Extract clean, structured content from URLs. Supports sync (1-10 URLs) and async (up to 50 URLs) modes.

# Basic extraction
response = valyu.contents(["https://arxiv.org/abs/2301.00001"])

# With AI summarization
response = valyu.contents(
    ["https://example.com/article"],
    summary=True,
    response_length="medium",
)

# Structured data extraction with JSON schema
response = valyu.contents(
    ["https://en.wikipedia.org/wiki/OpenAI"],
    summary={
        "type": "object",
        "properties": {
            "company_name": {"type": "string"},
            "founded_year": {"type": "integer"},
        },
    },
)

Answer

AI-generated answers grounded by Valyu's search. Supports streaming.

response = valyu.answer(
    "What are the side effects of metformin?",
    search_type="proprietary",
    included_sources=["valyu/valyu-pubmed"],
)

print(response.contents)        # AI-generated answer
print(response.search_results)  # Source citations

DeepResearch

Multi-step research agent that produces comprehensive reports with citations.

# Start a research task
task = valyu.deepresearch.create(
    input="Compare CRISPR and base editing approaches for sickle cell disease",
    model="heavy",
    output_formats=["markdown", "pdf"],
)

# Wait for completion with progress
def on_progress(status):
    print(f"Step {status.progress.current_step}/{status.progress.total_steps}")

result = valyu.deepresearch.wait(task.deepresearch_id, on_progress=on_progress)

print(result.output)   # Markdown report
print(result.pdf_url)  # PDF download link

All DeepResearch methods

Method	Description
create(...)	Start a new research task
status(task_id)	Get task status
wait(task_id, ...)	Poll until completion
stream(task_id, ...)	Stream real-time updates
list(api_key_id, limit)	List research tasks
update(task_id, instruction)	Add follow-up instruction
cancel(task_id)	Cancel a running task
delete(task_id)	Delete a task
toggle_public(task_id, is_public)	Toggle public access

Batch

Run multiple DeepResearch tasks in parallel.

batch = valyu.batch.create(
    name="Q1 Analysis",
    mode="fast",
    output_formats=["markdown"],
)

valyu.batch.add_tasks(batch.batch_id, tasks=[
    {"query": "Analyze recent SPAC performance"},
    {"query": "Review semiconductor supply chain trends"},
])

result = valyu.batch.wait_for_completion(
    batch.batch_id,
    on_progress=lambda b: print(f"{b.counts.completed}/{b.counts.total}"),
)

Data Sources

List available data sources programmatically.

sources = valyu.datasources.list()
categories = valyu.datasources.categories()

Authentication

export VALYU_API_KEY="your-api-key"

Or pass directly:

valyu = Valyu(api_key="your-api-key")

Type Safety

All request and response models use Pydantic v2:

from valyu.types.response import SearchResult, SearchResponse
from valyu.types.contents import ContentsResponse
from valyu.types.answer import AnswerSuccessResponse

Error Handling

response = valyu.search("test")

if not response.success:
    print(f"Error: {response.error}")
    print(f"tx_id: {response.tx_id}")

Integrations

Valyu works with LangChain, OpenAI, Anthropic, MCP, and more. See docs.valyu.ai for integration guides.

Links

• Documentation
• Platform & API Keys
• Discord
• GitHub Issues

License

MIT