Python Quickstart

The Valyu Python SDK gives you search, content extraction, answers, and deep research through one API.

Paste into your AI coding assistant to install the Valyu Python SDK and make your first search call.

Install

pip install valyu

Authenticate

Get your API key from the Valyu Platform ($10 free credits, $20 with a work email). The SDK reads VALYU_API_KEY from the environment automatically:

export VALYU_API_KEY="your-api-key-here"

from valyu import Valyu

valyu = Valyu()                    # reads VALYU_API_KEY
valyu = Valyu("your-api-key-here") # or pass it directly

First call

from valyu import Valyu

valyu = Valyu()

response = valyu.search("What are the latest developments in quantum computing?")

if not response.success:
    raise RuntimeError(response.error)

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

Every method returns a typed response with a success flag - check it before reading results.

APIs

Search

Search web and proprietary sources

Extract and process web content

Answer

Generate cited answers from search

DeepResearch

Autonomous async research reports

For multi-step synthesis or cited reports, reach for DeepResearch - a cost-effective autonomous agent built on the Valyu search engine - rather than hand-rolling a search loop.

Async client

AsyncValyu is the async/await counterpart to Valyu: same arguments, same response objects, same validation. Every method is a coroutine you await. Reach for it when a single request fans out several Valyu calls (research agents, multi-source lookups) or runs inside an async web service. For one-off scripts and notebooks, the synchronous client is simpler.

import asyncio
from valyu import AsyncValyu

async def main():
    async with AsyncValyu() as valyu:
        responses = await asyncio.gather(
            valyu.search("DCF terminal value assumptions"),
            valyu.search("GARCH volatility forecasting"),
        )
        for r in responses:
            print(r.query, len(r.results))

asyncio.run(main())

Bounded fan-out and streaming results

Cap how many requests are in flight with a semaphore (keep it aligned with max_connections):

import asyncio
from valyu import AsyncValyu

queries = [...]  # hundreds of queries

async def search_one(valyu, sem, query):
    async with sem:
        return await valyu.search(query, max_num_results=10)

async def main():
    async with AsyncValyu(max_connections=20) as valyu:
        sem = asyncio.Semaphore(20)
        await asyncio.gather(*[search_one(valyu, sem, q) for q in queries])

asyncio.run(main())

Use asyncio.as_completed to process each result the moment it’s ready instead of waiting for the whole batch.

FastAPI lifecycle

Instantiate the client once at startup and share it - don’t create a fresh AsyncValyu per request, or you throw away the connection pool every time.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from valyu import AsyncValyu

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.valyu = AsyncValyu()
    try:
        yield
    finally:
        await app.state.valyu.aclose()

app = FastAPI(lifespan=lifespan)

@app.get("/search")
async def search(q: str):
    response = await app.state.valyu.search(q)
    return {"results": [r.model_dump() for r in response.results]}

Prefer async with for scripts so the pool is released deterministically. For long-lived services, call aclose() on shutdown (it’s idempotent).

Constructor options

Parameter	Type	Description	Default
`api_key`	`Optional[str]`	API key. Falls back to `VALYU_API_KEY`.	`None`
`base_url`	`str`	Base URL of the Valyu API.	`https://api.valyu.ai/v1`
`max_connections`	`int`	Max simultaneous HTTP connections. Match it to your expected peak concurrency.	`100`
`max_keepalive_connections`	`Optional[int]`	Idle connections kept warm for reuse.	`max(20, max_connections // 5)`
`timeout`	`float`	Per-request timeout in seconds.	`600.0`
`http_client`	`Optional[httpx.AsyncClient]`	Pre-configured client to use instead of the default. Ownership stays with the caller.	`None`

AsyncValyu currently exposes search, contents, get_contents_job, and wait_for_contents_job. The remaining endpoints (answer, deepresearch, datasources) are synchronous-only today; async counterparts will follow.

Support

Discord: Join our community
GitHub: valyuAI/valyu-py
Email: contact@valyu.ai

SDKs

Python SDK

Install

Authenticate

First call

APIs

Search

Contents

Answer

DeepResearch

Async client

Support

​Install

​Authenticate

​First call

​APIs

Search

Contents

Answer

DeepResearch

​Async client

​Support

Install

Authenticate

First call

APIs

Async client

Support