Skip to main content

Valyu Python SDK

PyPI version License: MIT

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 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 ![alt](url) 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

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"},
        },
    },
)

# Replace image links in the content with their alt text
response = valyu.contents(
    ["https://example.com/article"],
    include_image_links=False,   # ![alt](url) becomes [Image: alt]
)

The include_image_links option (default True) is also available on valyu.search(). When it is False, image markdown ![alt](url) becomes [Image: alt], and images with no alt text are removed.

Answer

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 a DeprecationWarning. Use DeepResearch with mode="instant", or search() 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 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
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.

Edit a finished report

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 the id from the task's deliverables.
  • Focus. focus (a DeepResearchEditFocus or dict) points the edit at a passage (start_char/end_char UTF-16 offsets into the version's output, text, prefix, suffix) or a section heading. 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 (the version from status()) to fail with edit.revision_conflict instead of editing a report that changed since you read it. Pass idempotency_key so a retried request returns the same edit.
  • Outcomes. A finished edit is applied, declined (a normal outcome with decline.code, for example edit.out_of_evidence or edit.rewrite_requested; start a new task for those) or failed (error.code, for example edit.interrupted). A rejected request has success=False and an error_code such as edit.in_progress, edit.task_not_completed or focus.ambiguous (with candidates).
  • Versions. list_versions(task_id) lists every version (version 1 is the original), status(task_id, version=N) reads one, and restore_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

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}")

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.

Rate limits

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 retrying

If 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_url

rate_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")

Integrations

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

License

MIT

Metadata

Release files for valyu 2.14.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for valyu 2.14.1
File Size Uploaded Provenance Actions
valyu-2.14.1.tar.gz 97.5 kB With provenance Details for valyu-2.14.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for valyu 2.14.1
File Interpreter ABI Platform Actions
valyu-2.14.1-py3-none-any.whl Python 3 none any Details for valyu-2.14.1-py3-none-any.whl

Total release size: 178.1 kB

Release files / valyu-2.14.1.tar.gz

Download URL valyu-2.14.1.tar.gz
Size 97.5 kB
Tags Source
SHA-256 checksum
How to use checksums
6cbc17b8b571e6c88b04d6690309a4522d4fd4c1c0c4059913165514de4353ef
BLAKE2b-256 checksum
How to use checksums
8ac5e2b5e8d74cd450042b3495fc7375e6fce328bb0f2ec62081e899c16bf031
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 Nov 19, 2026.

Transparency log

Release files / valyu-2.14.1-py3-none-any.whl

Download URL valyu-2.14.1-py3-none-any.whl
Size 80.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e120c5527c69d3b4d612ec0fcd6c31519ca5aa2982917357cf626adcbecbe5d2
BLAKE2b-256 checksum
How to use checksums
c39f66f8f308af127f1d5b9e58579ead837bf652ce6f5813e7c61a188321ffaa
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 Nov 19, 2026.

Transparency log

Security for valyu 2.14.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for valyu-2.14.1.tar.gz

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 Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.14.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page