Valyu Best Practices

Valyu Best Practices

This skill provides instructions for using the Valyu API to perform search, content extraction, AI-powered answers, and deep research tasks.

Quick Reference: Choosing the Right API

Use this decision tree to select the appropriate Valyu API:

What do you need?

├─ Find information across multiple sources
│  └─ Use Search API
│
├─ Extract content from specific URLs
│  └─ Use Contents API
│
├─ Get an AI-synthesized answer with citations
│  └─ Use Answer API
│
├─ Generate a comprehensive research report
│  └─ Use DeepResearch API
│
└─ Discover available data sources
   └─ Use Datasources API

⚠️ MANDATORY: Use Official Valyu SDK Libraries

CRITICAL: When writing code that uses the Valyu API, you MUST use the official SDK libraries. NEVER make raw HTTP/fetch calls to the Valyu API endpoints.

JavaScript/TypeScript: valyu-js

npm install valyu-js
# or
pnpm add valyu-js

import { Valyu } from 'valyu-js';

const valyu = new Valyu(process.env.VALYU_API_KEY);

// Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deepResearch

Python: valyu

pip install valyu
# or
uv add valyu

from valyu import Valyu

valyu = Valyu(api_key=os.environ.get("VALYU_API_KEY"))

# Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deep_research

Why SDK Over Raw API Calls?

1. Type safety - Full TypeScript/Python type hints for all parameters and responses
2. Automatic retries - Built-in retry logic for transient failures
3. Streaming support - Proper async iterator support for streaming responses
4. Error handling - Structured error types with helpful messages
5. Future compatibility - SDK updates handle API changes automatically

❌ NEVER Do This

// DON'T make raw fetch calls
const response = await fetch('https://api.valyu.ai/v1/search', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: '...' })
});

✅ Always Do This

// DO use the SDK
import { Valyu } from 'valyu-js';

const valyu = new Valyu(process.env.VALYU_API_KEY);
const response = await valyu.search({ query: '...' });

1. Search API

Purpose: Find information across web, academic, medical, transportation, financial, news, and proprietary sources.

When to Use

• Finding recent information on any topic
• Academic research (arXiv, PubMed, bioRxiv, medRxiv)
• Financial data (SEC filings, earnings reports, stock data)
• News monitoring and current events
• Healthcare data (clinical trials, drug labels)
• Prediction markets (Polymarket, Kalshi)
• Transportation (UK National Rail, Global Shipping)

Basic Usage

const response = await valyu.search({
  query: "transformer architecture attention mechanism 2024",
  searchType: "all",
  maxNumResults: 10
});

Search Types

Key Parameters

Domain-Specific Search Patterns

Academic Research:

await valyu.search({
  query: "CRISPR therapeutic applications clinical trials",
  searchType: "proprietary",
  includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "valyu/valyu-biorxiv"],
  startDate: "2024-01-01"
});

Financial Analysis:

await valyu.search({
  query: "Apple revenue Q4 2024 earnings",
  searchType: "all",
  includedSources: ["valyu/valyu-sec-filings", "valyu/valyu-earnings-US"]
});

News Monitoring:

await valyu.search({
  query: "AI regulation EU",
  searchType: "news",
  startDate: "2024-06-01",
  countryCode: "EU"
});

Search Recipes

For detailed patterns, see:

• Basic Search Patterns
• Academic Search
• Finance Search
• News Search
• Healthcare Search

2. Contents API

Purpose: Extract clean, structured content from web pages optimized for LLM processing.

When to Use

• Converting web pages to clean markdown
• Extracting article text for summarization
• Parsing documentation for RAG systems
• Structured data extraction from product pages
• Processing academic papers

Basic Usage

const response = await valyu.contents({
  urls: ["https://example.com/article"]
});

With Summarization

const response = await valyu.contents({
  urls: ["https://arxiv.org/abs/2401.12345"],
  summary: "Extract key findings in 3 bullet points"
});

Structured Extraction (JSON Schema)

const response = await valyu.contents({
  urls: ["https://example.com/product"],
  summary: {
    type: "object",
    properties: {
      product_name: { type: "string" },
      price: { type: "number" },
      features: { type: "array", items: { type: "string" } }
    },
    required: ["product_name", "price"]
  }
});

Key Parameters

Content Recipes

For detailed patterns, see:

• Basic Content Extraction
• Extraction with Summary
• Structured Extraction
• Research Paper Extraction

3. Answer API

Purpose: Get AI-powered answers grounded in real-time search results with citations.

When to Use

• Questions requiring current information synthesis
• Multi-source fact verification
• Technical documentation questions
• Research requiring cited sources
• Structured data extraction from search results

Basic Usage

const response = await valyu.answer({
  query: "What are the latest developments in quantum computing?"
});

With Fast Mode (Lower Latency)

const response = await valyu.answer({
  query: "Current Bitcoin price and 24h change",
  fastMode: true
});

With Custom Instructions

const response = await valyu.answer({
  query: "Compare React and Vue for enterprise applications",
  systemInstructions: "Provide a balanced comparison with pros and cons. Format as a comparison table."
});

With Streaming

const stream = await valyu.answer({
  query: "Explain transformer architecture",
  streaming: true
});

for await (const chunk of stream) {
  // Handle: search_results, content, metadata, done, error
  console.log(chunk);
}

Structured Output

const response = await valyu.answer({
  query: "Apple Q4 2024 financial highlights",
  structuredOutput: {
    type: "object",
    properties: {
      revenue: { type: "string" },
      growthRate: { type: "string" },
      keyHighlights: { type: "array", items: { type: "string" } }
    }
  }
});

Key Parameters

Answer Recipes

For detailed patterns, see:

• Basic Answer
• Fast Mode
• Streaming
• Custom Instructions

4. DeepResearch API

Purpose: Generate comprehensive research reports with detailed analysis and citations.

When to Use

• Comprehensive market analysis
• Literature reviews
• Competitive intelligence
• Technical deep dives
• Topics requiring multi-source synthesis

Research Modes

Create Research Task

const task = await valyu.deepResearch.create({
  query: "AI chip market competitive landscape 2024",
  model: "standard"
});
// Returns: { deepresearch_id: "abc123", status: "queued" }

Poll for Completion

const status = await valyu.deepResearch.getStatus(task.deepresearch_id);
// status: "queued" | "running" | "completed" | "failed" | "cancelled"

if (status.status === "completed") {
  console.log(status.output);  // Markdown report
  console.log(status.sources); // Cited sources
  console.log(status.pdf_url); // PDF download link
}

Key Parameters

DeepResearch Recipes

For detailed patterns, see:

• Fast Research
• Standard Research
• Heavy Research

5. Query Writing Best Practices

Core Principles

1. Be specific - Use domain terminology
2. Be concise - Keep queries under 400 characters
3. Be focused - One topic per query
4. Add constraints - Include timeframes, source types

Query Anatomy

Good vs Bad Queries

BAD:  "I want to know about AI"
GOOD: "transformer attention mechanism survey 2024"

BAD:  "Apple financial information"
GOOD: "Apple revenue growth Q4 2024 earnings SEC filing"

BAD:  "gene editing research"
GOOD: "CRISPR off-target effects therapeutic applications 2024"

Split Complex Requests

# Don't do this
"Tesla stock performance, new products, and Elon Musk statements"

# Do this instead
Query 1: "Tesla stock performance Q4 2024"
Query 2: "Tesla Cybertruck production updates 2024"
Query 3: "Tesla FSD autonomous driving progress"

Source Filtering

Use includedSources for domain authority: ​ Financial Research Collection. Some sources to include:

• valyu/valyu-sec-filings - SEC regulatory filings
• valyu/valyu-stocks - Stock market data
• valyu/valyu-earnings-US - Earnings reports
• reuters.com - Financial news
• bloomberg.com - Market analysis ​ Medical Research Collection. Some sources to include:
• valyu/valyu-pubmed - Medical literature
• valyu/valyu-clinical-trials - Clinical trial data
• valyu/valyu-drug-labels - FDA drug information
• nejm.org - New England Journal of Medicine
• thelancet.com - The Lancet ​ Tech Documentation Collection. Some sources to include:
• docs.aws.amazon.com - AWS documentation
• cloud.google.com/docs - Google Cloud docs
• learn.microsoft.com - Microsoft docs
• kubernetes.io/docs - Kubernetes docs
• developer.mozilla.org - MDN Web Docs

// Academic
includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "nature"]

// Financial
includedSources: ["valyu/valyu-sec-filings", "bloomberg.com", "reuters.com"]

// Tech news
includedSources: ["techcrunch.com", "theverge.com", "arstechnica.com"]

For complete prompting guide, see references/prompting.md.

6. Common Workflows

Research Workflow

// 1. Quick search to find sources
const searchResults = await valyu.search({
  query: "CRISPR therapeutic applications",
  searchType: "proprietary",
  maxNumResults: 20
});

// 2. Extract key content from top results
const contents = await valyu.contents({
  urls: searchResults.results.slice(0, 3).map(r => r.url),
  summary: "Extract key findings"
});

// 3. Deep analysis for comprehensive report
const research = await valyu.deepResearch.create({
  query: "CRISPR therapeutic applications comprehensive review",
  model: "heavy"
});

Financial Analysis Workflow

// 1. Get SEC filings
const filings = await valyu.search({
  query: "Apple 10-K 2024",
  includedSources: ["valyu/valyu-sec-filings"]
});

// 2. Quick synthesis
const summary = await valyu.answer({
  query: "Apple Q4 2024 financial highlights",
  fastMode: true
});

// 3. Structured extraction
const metrics = await valyu.answer({
  query: "Apple financial metrics 2024",
  structuredOutput: {
    type: "object",
    properties: {
      revenue: { type: "string" },
      netIncome: { type: "string" },
      growthRate: { type: "string" }
    }
  }
});

7. Available Data Sources

Valyu provides access to 25+ specialized datasets:

For complete datasource reference, see references/datasources.md.

8. API Reference

For complete API documentation including all parameters, response structures, and error codes, see references/api-guide.md.

9. Integration Guides

Platform-specific integration documentation:

• Anthropic Claude
• OpenAI
• Vercel AI SDK
• LangChain
• LlamaIndex
• MCP Server

Additional Resources

• All Recipes Index
• Design Philosophy
• Prompting Guide
• Full API Reference