Skip to main content
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.

Open in Cursor

​
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

Contents

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())
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.
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).
ParameterTypeDescriptionDefault
api_keyOptional[str]API key. Falls back to VALYU_API_KEY.None
base_urlstrBase URL of the Valyu API.https://api.valyu.ai/v1
max_connectionsintMax simultaneous HTTP connections. Match it to your expected peak concurrency.100
max_keepalive_connectionsOptional[int]Idle connections kept warm for reuse.max(20, max_connections // 5)
timeoutfloatPer-request timeout in seconds.600.0
http_clientOptional[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