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
pip install valyufrom 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.
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 |
include_image_links |
bool |
True |
When False, image markdown  in result content becomes [Image: alt] and images with no alt text are removed |
category |
str |
None |
Category filter |
fast_mode |
bool |
False |
Faster results, shorter content |
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"},
},
},
)
# Replace image links in the content with their alt text
response = valyu.contents(
["https://example.com/article"],
include_image_links=False, #  becomes [Image: alt]
)The include_image_links option (default True) is also available on valyu.search(). When it is False, image markdown  becomes [Image: alt], and images with no alt text are removed.
Deprecated. The Answer API is deprecated (announced 2026-11-17) and stops working on 2026-12-17, when the endpoint returns HTTP 410.
valyu.answer()still works until then but emits aDeprecationWarning. Use DeepResearch withmode="instant", orsearch()plus your own LLM. See the migration guide.
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 citationsMulti-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 linkAll 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 |
edit(task_id, instruction, ...) |
Edit a finished report or deliverable |
get_edit(task_id, edit_id) |
Get one edit |
list_edits(task_id) |
List a task's edits |
wait_for_edit(task_id, edit_id, ...) |
Poll until an edit finishes |
list_versions(task_id) |
List report versions |
restore_version(task_id, version) |
Restore an earlier version |
Modes. mode is one of "instant", "fast", "standard" (default), "heavy" or "max". "instant" is the quickest and lowest-cost mode and typically finishes in under 30 seconds; it does not support hitl checkpoints and is not available for batches.
task = valyu.deepresearch.create(query="What is the capital of Australia?", mode="instant")
result = valyu.deepresearch.wait(task.deepresearch_id)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.
Make small, targeted edits to a finished DeepResearch report or deliverable with a plain-language instruction. Untouched text stays exactly as it was, citations stay consistent, and every edit creates a new version you can restore.
result = valyu.deepresearch.wait(task.deepresearch_id)
if result.editable:
edit = valyu.deepresearch.edit(
task.deepresearch_id,
"Cut the executive summary to 3 bullets and add the Q3 revenue figure with its citation.",
focus={"section": "Executive Summary", "scope": "strict"},
base_version=result.version,
wait_seconds=15,
)
if edit.success and edit.status == "running":
edit = valyu.deepresearch.wait_for_edit(task.deepresearch_id, edit.edit_id)
if edit.status == "applied":
print(f"Version {edit.version}: {edit.summary}")
updated = valyu.deepresearch.status(task.deepresearch_id)
elif edit.status == "declined":
print(edit.decline.code, edit.decline.suggestion)
else:
print(edit.error_code, edit.error)- Target. Edits change the report by default. Pass
target={"kind": "deliverable", "deliverable_id": "f_01"}to edit a deliverable file, using theidfrom the task'sdeliverables. - Focus.
focus(aDeepResearchEditFocusor dict) points the edit at a passage (start_char/end_charUTF-16 offsets into the version'soutput,text,prefix,suffix) or asectionheading.scope="strict"rejects any change outside it; the default is"prefer". - Citations.
citations="stable"(the default) keeps existing citation numbers;"compact"renumbers them by first appearance. - Concurrency. Pass
base_version(theversionfromstatus()) to fail withedit.revision_conflictinstead of editing a report that changed since you read it. Passidempotency_keyso a retried request returns the same edit. - Outcomes. A finished edit is
applied,declined(a normal outcome withdecline.code, for exampleedit.out_of_evidenceoredit.rewrite_requested; start a new task for those) orfailed(error.code, for exampleedit.interrupted). A rejected request hassuccess=Falseand anerror_codesuch asedit.in_progress,edit.task_not_completedorfocus.ambiguous(withcandidates). - Versions.
list_versions(task_id)lists every version (version 1 is the original),status(task_id, version=N)reads one, andrestore_version(task_id, N)makes version N current again as a new version. No version is deleted.
Guide: https://docs.valyu.ai/guides/deepresearch-editing
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}"),
)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 |
List available data sources programmatically.
sources = valyu.datasources.list()
categories = valyu.datasources.categories()export VALYU_API_KEY="your-api-key"Or pass directly:
valyu = Valyu(api_key="your-api-key")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 AnswerSuccessResponseresponse = valyu.search("test")
if not response.success:
print(f"Error: {response.error}")
print(f"tx_id: {response.tx_id}")Search, answer and DeepResearch responses may also carry non-fatal warnings (a list of ResponseWarning with type, message and optional detail), for example when a requested dataset isn't included in your plan and was skipped.
A request that exceeds your plan's rate limit gets back HTTP 429. search(), contents(), answer(), deepresearch.create(), batch.create(), and batch.add_tasks() retry it automatically — a 429 means the request was never accepted or billed, so retrying is always safe. Each retry waits the amount of time the response asks for (capped at 60 seconds), up to max_rate_limit_retries attempts (default 2):
valyu = Valyu(max_rate_limit_retries=5) # default is 2; use 0 to disable retryingIf every retry is also rate limited, the call still returns its normal response model with success=False, plus a structured rate_limit field:
response = valyu.search("test")
if response.rate_limit:
print(f"Retry after: {response.rate_limit.retry_after}s")
print(f"Plan: {response.rate_limit.plan}")
print(f"Limit: {response.rate_limit.limit}") # {"endpoint": ..., "requests_per_second": ...}
print(f"Upgrade: {response.rate_limit.upgrade_url}") # self-serve plans
print(f"Contact: {response.rate_limit.contact_url}") # enterprise plans, instead of upgrade_urlrate_limit is None for any other error. Older API responses that send only a generic rate-limit message leave plan/limit/upgrade_url/contact_url as None too — retry_after is always set.
The one method that raises on an HTTP error (deepresearch.get_assets()) raises a typed RateLimitError instead, carrying the same fields:
from valyu import RateLimitError
try:
data = valyu.deepresearch.get_assets(task_id, asset_id)
except RateLimitError as e:
print(f"Rate limited, retry after {e.retry_after}s")Valyu works with LangChain, OpenAI, Anthropic, MCP, and more. See docs.valyu.ai for integration guides.
MIT