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

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

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.

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.13.5

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.13.5
File Size Uploaded Provenance Actions
valyu-2.13.5.tar.gz 83.3 kB With provenance Details for valyu-2.13.5.tar.gz

Built distribution (wheel)

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

Total release size: 156.3 kB

Release files / valyu-2.13.5.tar.gz

Download URL valyu-2.13.5.tar.gz
Size 83.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bf90a9e9990ba44122e4b0e0d32e4605c46210ae90debf5f8eff4a6aeff1abcf
BLAKE2b-256 checksum
How to use checksums
6e5cce29e864d80e48625238e141d6dcaa36a70e3b6363c24f6f024686cb2359
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 31, 2026.

Transparency log

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

Download URL valyu-2.13.5-py3-none-any.whl
Size 73.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dd18b3036739daea5f2ab3d4e54b890296d7c5def2029195b4779feb33d6eecb
BLAKE2b-256 checksum
How to use checksums
33b26206fa396aefbcfba2623988241ffaa8d0350592cf2c2ef0c937e2a4493d
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 31, 2026.

Transparency log

Security for valyu 2.13.5

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.13.5.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 Oct 31, 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.13.5 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