​

Valyu for AI agents

​

Set up

• Base URL: https://api.valyu.ai. Auth: x-api-key: $VALYU_API_KEY header. Keep keys server-side, in environment variables, out of source control and logs.
• Keys, balance and plans: https://platform.valyu.ai. New accounts get 10 USD of free credits (20 USD with a company email), no card.
• SDKs: Python pip install valyu (from valyu import Valyu), TypeScript pnpm add valyu-js (import { Valyu } from "valyu-js"). Both read VALYU_API_KEY. Rust SDK is alpha.
• CLI: curl -fsSL https://get.valyu.ai | bash, then valyu login. Agent runbook: https://www.valyu.ai/agents.md.
• MCP (chat apps and coding agents): https://mcp.valyu.ai/mcp (sign-in), or ?valyuApiKey=KEY for clients that can’t sign in.
• Docs index: https://docs.valyu.ai/llms.txt. Append .md to any docs URL for Markdown. OpenAPI: https://docs.valyu.ai/api-reference/openapi.json.

​

Pick the endpoint

​

Search

curl https://api.valyu.ai/v1/search -H "x-api-key: $VALYU_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "Apple 10-K Item 1A risk factors", "search_type": "all", "max_num_results": 10}'

• query: natural language. Name the entity, document and period (“Microsoft fiscal Q4 2025 earnings call capex”).
• search_type: all (default, web + specialist), web, proprietary, news.
• max_num_results: up to 20 by default.
• included_sources / excluded_sources: domains ("arxiv.org"), dataset IDs ("valyu/valyu-sec-filings"), presets ("academic", "finance", "patent", "health", "chemistry", "physics", "legal", "politics", "genomics", "transportation"), "web", or "collection:NAME".
• start_date / end_date: YYYY-MM-DD. response_length: short (25k chars, default), medium, large, max or an integer.
• source_biases: {"source": -5..5} to rank sources up or down without filtering.
• include_image_links: true (default) keeps image markdown. false turns each image into [Image: alt text] to save tokens. Also on POST /v1/contents.
• Keep url and source with every passage you pass to a model. Check success; an empty results array is not an error.

​

DeepResearch

curl https://api.valyu.ai/v1/deepresearch/tasks -H "x-api-key: $VALYU_API_KEY" -H "Content-Type: application/json" -d '{
  "query": "Compare capex guidance from Microsoft, Alphabet, Amazon and Meta on their last three earnings calls.",
  "mode": "standard",
  "research_strategy": "Use transcripts, earnings releases and 10-Qs. Quote management exactly.",
  "report_format": "Summary, a table by company and call, one short section per company.",
  "deliverables": [{"type": "csv", "description": "One row per company per call with source URL", "columns": ["company", "call_date", "guidance_quote", "source_url"]}]
}'
# Save deepresearch_id, then poll GET /v1/deepresearch/tasks/{id}/status until status is completed or failed.

• mode: instant, fast, standard (default), heavy, max. Time limits: 2, 10, 20, 45 and 90 minutes. Credits: 8, 25, 100, 500, 2,500.
• deliverables: up to 10 files, csv, xlsx, pptx, docx or pdf (every mode except instant). xlsx, pptx and docx need "tools": {"code_execution": {"enabled": true}}. Each file comes back in deliverables[] with status and a signed url that expires.
• output_formats: ["markdown"] (default), add "pdf", or pass a JSON Schema for structured output.
• search: same source controls as Search (included_sources, source_biases, start_date, end_date). reference_date (2026 onwards) pins the run to a past date for backtests (REST only for now; the TypeScript SDK doesn’t forward it).
• urls (max 10) and files (max 10) add your own material. previous_reports (max 3) continues earlier work.
• Results: output (markdown with numbered citations), sources[] (title, url, and optional locations[].excerpt passages, which the released SDKs don’t expose yet: read the raw status response), deliverables[], pdf_url, cost.
• Make a report shareable: POST /v1/deepresearch/tasks/{id}/public with {"public": true}; link https://platform.valyu.ai/share/{id}.
• Persist the task ID before polling. Don’t create a duplicate after a client timeout; check the existing task. Use webhook_url instead of polling where you can.
• Don’t run paid research tasks on a user’s behalf without their confirmation; state the mode and its credits first.

​

Errors

​

Honesty rules for agents

• Preserve source attribution. A citation shows where a claim came from; it doesn’t certify the claim.
• Don’t promise exhaustive retrieval or universal full-text access, and don’t state licence or contract terms for licensed content. Describe Wiley sources as available for purchase by eligible startups, pay-per-use, with access requested in the platform.
• Source availability, plan access and endpoint support are different facts. Some datasets are DeepResearch-only; licensed sources need access first.
• Quote prices from https://docs.valyu.ai/pricing rather than copying rates into prompts.

​

Contributing to these docs