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
include_abstracts=True, # search the full PubMed abstract corpus
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 |
include_abstracts |
bool |
False |
Search PubMed's complete abstract corpus instead of full-text papers |
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 |
Polling. status(), wait() and stream() poll conditionally. When the server returns an ETag, the next poll for that task sends it as If-None-Match; a 304 Not Modified reuses the previous response with no body transferred, and on_progress / stream progress callbacks are not repeated for a 304. When poll_interval is not set, wait() and stream() follow the server's Retry-After hint (clamped to 1-30 seconds, default 5); an explicit poll_interval always wins. Rate limits (429) and server errors (5xx) are retried with jittered exponential backoff. Servers that send no ETag are polled exactly as before.
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}"),
)
Workflows
Templated DeepResearch starting points - curated by Valyu or created by your org - with typed {variable} placeholders and version history.
# Browse curated workflows
catalog = valyu.workflows.list(scope="valyu", vertical="investment-banking")
for wf in catalog.workflows:
print(wf.slug, "-", wf.title)
# Run one as a DeepResearch task
task = valyu.deepresearch.create(
workflow_id="ib-company-profile",
workflow_params={"company": "NVIDIA (NVDA)"},
)
result = valyu.deepresearch.wait(task.deepresearch_id)
print(result.output)
Create your own:
valyu.workflows.create(
slug="weekly-competitor-scan",
title="Weekly Competitor Scan",
version={
"prompt": "Summarize the week's most important developments at {company}.",
"strategy": "Prioritize primary sources: filings, press releases, earnings calls.",
"report_format": "Bullet-point briefing, grouped by theme.",
"variables": [{"key": "company", "label": "Company", "required": True}],
},
)
All Workflows methods
| Method | Description |
|---|---|
list(vertical, scope, q, tags, limit, expand) |
List available workflows |
get(slug, version) |
Get a workflow's full template |
versions(slug) |
List a workflow's version history |
preview(slug, workflow_params, workflow_version) |
Resolve the template without creating a task |
create(slug, title, version, ...) |
Create an org workflow |
update(slug, ..., version, set_current) |
Update metadata and/or publish a new version |
delete(slug) |
Delete an org workflow |
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
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for valyu 2.12.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| valyu-2.12.3.tar.gz | 62.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| valyu-2.12.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 124.6 kB
Release files / valyu-2.12.3.tar.gz
| Download URL | valyu-2.12.3.tar.gz |
|---|---|
| Size | 62.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7318f6c49b0797da9b72a9f03826f5774465ce7c5a99e594e41551c34f8f8d99
|
|
BLAKE2b-256 checksum How to use checksums |
3fc91444326afb6a461ca11b35dd902b1fd227aa6bd8338e05a3d336ea07b21c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / valyu-2.12.3-py3-none-any.whl
| Download URL | valyu-2.12.3-py3-none-any.whl |
|---|---|
| Size | 62.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
78f75a241632eea760ce976962d485f73400d816415edc04d5d26b90f7473d03
|
|
BLAKE2b-256 checksum How to use checksums |
c15b6812c4f954b319a5be2e80274ecff380d24e4a98454cb42123bf80bc47ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency log
