Valyu Search

Valyu Complete API Tool

Reference Documentation

For detailed guidance, consult these references:

Integrations

When users ask how to integrate Valyu with other platforms or SDKs, consult the integration guides:

Comprehensive CLI tool for all Valyu APIs: Search, Answer, Contents, and DeepResearch.

CRITICAL: Script Path Resolution

IMPORTANT: The scripts/valyu commands in this documentation are relative to this skill's installation directory, NOT the user's current working directory.

Finding the Script Path

Before running any command, you MUST locate the script using one of these methods:

1. For marketplace installs, the script is at:

   ~/.claude/plugins/cache/valyu-marketplace/valyu-search-plugin/<version>/skills/valyu-search/scripts/valyu

2. Quick method - Find it dynamically:

   VALYU_SCRIPT=$(find ~/.claude/plugins/cache -name "valyu" -path "*/valyu-search-plugin/*/scripts/*" -type f 2>/dev/null | head -1)

3. Then use the full path for all commands:

   $VALYU_SCRIPT search web "query"
   # OR use the full path directly:
   ~/.claude/plugins/cache/valyu-marketplace/valyu-search-plugin/1.0.0/skills/valyu-search/scripts/valyu search web "query"

4. Self-location commands - Once you have the path, you can verify it:

   /path/to/valyu --path      # Prints the script's full path
   /path/to/valyu --script-dir # Prints the script's directory

Important Notes

• NEVER run scripts/valyu directly - it will fail with "no such file or directory"
• ALWAYS use the full absolute path to the script
• The version number in the path (e.g., 1.0.0) may change with updates

IMPORTANT: API Key Setup Flow

When you run any Valyu command and receive a response with "setup_required": true, follow this flow:

1. Ask the user for their API key: "To use Valyu search, I need your API key. You can get one free ($10 credits) at https://platform.valyu.ai. Please paste your API key."

2. Once the user provides the key, run the setup command:

   scripts/valyu setup <api-key>

3. After successful setup, retry the original command.

Example Flow:

User: Valyu(web, "AI news")
→ Response: {"success": false, "setup_required": true, ...}
→ Claude asks: "Please provide your Valyu API key from https://platform.valyu.ai"
→ User: "val_abc123..."
→ Claude runs: scripts/valyu setup val_abc123...
→ Response: {"success": true, "type": "setup", "message": "API key saved..."}
→ Claude retries: scripts/valyu search web "AI news"
→ Success!

Requirements

1. Node.js 18+ (uses built-in fetch) 2. API key from https://platform.valyu.ai (setup automatically via scripts/valyu setup <key>) 3. Scripts are executable (already set in packaged skill)

Commands Overview

0. SETUP - Configure API key (auto-triggered on first use)

scripts/valyu setup <api-key>

1. SEARCH - Multi-domain search

scripts/valyu search <type> <query> [maxResults]

2. ANSWER - AI-powered answers

scripts/valyu answer <query> [--fast] [--structured <schema>]

3. CONTENTS - Extract content from URLs

scripts/valyu contents <url> [--summary [instructions]] [--structured <schema>]

4. DEEPRESEARCH - Async research reports

scripts/valyu deepresearch create <query> [--model <fast|lite|heavy>] [--pdf]
scripts/valyu deepresearch status <task-id>

1. SEARCH API

Search Types

Usage Examples

# Web search
scripts/valyu search web "AI developments 2025" 10

# Academic papers
scripts/valyu search paper "transformer architectures" 15

# Financial data
scripts/valyu search finance "Apple earnings Q4 2024" 8

# Biomedical research
scripts/valyu search bio "cancer immunotherapy clinical trials"

Output Format

{
  "success": true,
  "type": "search",
  "searchType": "web",
  "query": "AI news",
  "resultCount": 10,
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com",
      "content": "Full content...",
      "source": "web",
      "relevance_score": 0.95
    }
  ],
  "cost": 0.025
}

2. ANSWER API

AI-powered answers with real-time search integration.

Basic Usage

# Simple answer
scripts/valyu answer "What is quantum computing?"

# Fast mode (quicker, less comprehensive)
scripts/valyu answer "Latest AI news" --fast

# With structured output
scripts/valyu answer "Top tech companies 2024" --structured '{
  "type": "object",
  "properties": {
    "companies": {
      "type": "array",
      "items": {"type": "string"}
    },
    "market_summary": {"type": "string"}
  }
}'

Features

• Fast Mode: Lower latency, finance and web sources prioritized
• Structured Output: Define JSON schema for consistent responses
• Source Citations: Returns sources used in the answer
• Search Integration: Automatically searches relevant sources

Output Format

{
  "success": true,
  "type": "answer",
  "query": "What is quantum computing?",
  "answer": "Quantum computing is...",
  "data_type": "unstructured",
  "sources": [
    {
      "title": "Source Title",
      "url": "https://example.com"
    }
  ],
  "cost": 0.032
}

3. CONTENTS API

Extract clean, structured content from web pages.

Basic Usage

# Extract raw content
scripts/valyu contents "https://techcrunch.com/article"

# Extract with AI summary
scripts/valyu contents "https://example.com" --summary

# Extract with custom instructions
scripts/valyu contents "https://example.com" --summary "Summarize key findings in 2 paragraphs"

# Extract structured data
scripts/valyu contents "https://product-page.com" --structured '{
  "type": "object",
  "properties": {
    "product_name": {"type": "string"},
    "price": {"type": "number"},
    "features": {
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "required": ["product_name", "price"]
}'

Features

• Batch Processing: Process multiple URLs (up to 10)
• AI-Powered Summarization: Generate summaries with custom instructions
• Structured Extraction: Extract specific data points using JSON schema
• Response Length Control: short (25k), medium (50k), large (100k), max
• Extract Effort: normal, high, auto

Response Length Options

Output Format

{
  "success": true,
  "type": "contents",
  "urls_requested": 1,
  "urls_processed": 1,
  "urls_failed": 0,
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com",
      "content": "Extracted content...",
      "data_type": "unstructured",
      "summary_success": true,
      "length": 12840
    }
  ],
  "total_cost": 0.001
}

4. DEEPRESEARCH API

Asynchronous deep research with comprehensive reports.

Research Modes

Create Research Task

# Basic research (lite mode, markdown)
scripts/valyu deepresearch create "AI market trends 2024"

# Heavy mode with PDF output
scripts/valyu deepresearch create "Climate change mitigation strategies" --model heavy --pdf

# Fast mode for quick lookup
scripts/valyu deepresearch create "Current Bitcoin price trends" --model fast

Check Task Status

scripts/valyu deepresearch status f992a8ab-4c91-4322-905f-190107bd5a5b

Output Formats

• Markdown: Default, clean formatted report
• PDF: Add --pdf flag for downloadable PDF
• JSON Schema: Custom structured output (advanced)

Task Lifecycle

queued → running → completed/failed

Statuses:

• queued: Waiting to start
• running: Actively researching
• completed: Research finished
• failed: Error occurred
• cancelled: User cancelled

Create Response

{
  "success": true,
  "type": "deepresearch_create",
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "queued",
  "query": "AI market trends 2024",
  "model": "lite",
  "created_at": 1759617800000
}

Status Response

{
  "success": true,
  "type": "deepresearch_status",
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "completed",
  "query": "AI market trends 2024",
  "output": "# AI Market Trends 2024\n\n## Overview...",
  "pdf_url": "https://storage.valyu.ai/reports/...",
  "sources": [
    {
      "title": "Market Analysis 2024",
      "url": "https://example.com",
      "snippet": "Key findings...",
      "source": "web",
      "word_count": 2500
    }
  ],
  "progress": {
    "current_step": 5,
    "total_steps": 5
  },
  "usage": {
    "search_cost": 0.0075,
    "ai_cost": 0.15,
    "total_cost": 0.1575
  },
  "completed_at": 1759617836483
}

Processing Results

With jq

# Get search result titles
scripts/valyu search web "AI" 5 | jq '.results[].title'

# Get answer text
scripts/valyu answer "What is AI?" | jq -r '.answer'

# Get extracted content
scripts/valyu contents "https://example.com" | jq -r '.results[].content'

# Get research output
scripts/valyu deepresearch status <task-id> | jq -r '.output'

# Check if completed
result=$(scripts/valyu deepresearch status <task-id>)
if echo "$result" | jq -e '.status == "completed"' > /dev/null; then
  echo "Research complete!"
fi

Error Handling

All commands return JSON with success field:

{
  "success": false,
  "error": "Error message"
}

Exit codes:

• 0 - Success
• 1 - Error (check JSON for details)

Use Cases

Research Assistant

# Deep research with PDF
scripts/valyu deepresearch create "Blockchain in healthcare" --model heavy --pdf

News Monitoring

# Latest news
scripts/valyu search news "AI regulation EU" 20

Content Aggregation

# Extract and summarize
scripts/valyu contents "https://blog.com/post" --summary "Key takeaways in bullet points"

Quick Q&A

# Fast answer
scripts/valyu answer "Who won the 2024 election?" --fast

Academic Research

# Search papers
scripts/valyu search paper "CRISPR gene editing 2024" 15

Financial Analysis

# Get financial data
scripts/valyu search finance "Tesla stock performance 2024" 10

Requirements

• Node.js 18+ - For built-in fetch API
• VALYU_API_KEY - Environment variable
• No npm packages - Direct API calls only

Get API key: https://platform.valyu.ai ($10 free credits)

API Endpoints Used

• /v1/search - Search API
• /v1/answer - Answer API
• /v1/contents - Contents API
• /v1/deepresearch/tasks - DeepResearch API
• /v1/deepresearch/tasks/{id}/status - Task status

Architecture

scripts/
├── valyu          # Bash wrapper
└── valyu.mjs      # Node.js CLI (all APIs)

Direct API calls using Node.js built-in fetch(), zero external dependencies.

Answer with Custom Instructions

Guide the AI on how to process and format the answer using systemInstructions.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.answer({
  query: "climate change research",
  systemInstructions: "Focus on practical applications and commercial impact. Summarise key findings as bullet points."
});

console.log(data.contents);

from valyu import Valyu

valyu = Valyu()

data = valyu.answer(
    query="climate change research",
    system_instructions="Focus on practical applications and commercial impact. Summarise key findings as bullet points."
)

print(data["contents"])

Example Instructions

• "Respond in bullet points"
• "Focus on technical details"
• "Summarize in 2-3 paragraphs"
• "Include specific numbers and statistics"
• "Write for a non-technical audience"
• "Compare and contrast the options"

Answer with Fast Mode

Enable fast mode for quicker responses with lower latency.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.answer({
  query: "current market trends in tech stocks",
  fastMode: true,
  dataMaxPrice: 30.0
});

console.log(data.contents);

from valyu import Valyu

valyu = Valyu()

data = valyu.answer(
    query="current market trends in tech stocks",
    fast_mode=True,
    data_max_price=30.0
)

print(data["contents"])

CLI

scripts/valyu answer "current market trends in tech stocks" --fast

When to Use Fast Mode

• Quick lookups and simple questions
• Time-sensitive queries
• When lower cost is preferred
• Real-time applications

Answer with Streaming

Enable streaming for progressive answer generation.

The stream sends data in sequence: search results first, then content chunks, then metadata.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const stream = await valyu.answer({
  query: "Explain the implications of recent AI regulation",
  streaming: true
});

for await (const chunk of stream) {
  switch (chunk.type) {
    case 'search_results':
      console.log('Sources found:', chunk.data.length);
      break;
    case 'content':
      process.stdout.write(chunk.data);
      break;
    case 'metadata':
      console.log('\nCost:', chunk.data.cost);
      break;
    case 'done':
      console.log('\nComplete');
      break;
    case 'error':
      console.error('Error:', chunk.data);
      break;
  }
}

Chunk Types

Basic Answer

AI-powered answers with real-time search. Searches across web, academic, and financial sources, then uses AI to generate a readable response.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.answer({
  query: "latest developments in quantum computing",
});

console.log(data.contents);

from valyu import Valyu

valyu = Valyu()  # Uses VALYU_API_KEY from env

data = valyu.answer(
    query="latest developments in quantum computing",
)

print(data["contents"])

CLI

scripts/valyu answer "What are the latest developments in quantum computing?"

Valyu API Reference Guide

Complete API documentation for all Valyu endpoints. Use this reference when implementing searches, content extraction, AI-powered answers, or deep research.

API Overview

Authentication

All endpoints require the x-api-key header:

x-api-key: your_valyu_api_key

Get your API key at https://platform.valyu.ai ($10 free credits).

---

Search API (POST /v1/search)

Real-time search across web, academic, financial, economic, medical research, news, patents, prediction markets, transportation and proprietary data sources.

Parameters

Search Types Explained

• `all`: Searches everything - web, academic papers, financial data,economic, medical research, news, patents, prediction markets, transportation,proprietary sources
• `web`: General internet content only
• `proprietary`: Licensed academic papers, research, books
• `news`: News articles and current events

Response Structure

{
  "success": true,
  "tx_id": "tx_abc123",
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com/article",
      "content": "Full extracted content in markdown...",
      "source": "web",
      "relevance_score": 0.92,
      "publication_date": "2024-01-15",
      "length": 5420,
      "price": 0.002
    }
  ],
  "total_results": 10,
  "total_deduction_dollars": 0.025,
  "total_characters": 54200
}

When to Use Search

• Finding recent information on any topic
• Academic research across arXiv, PubMed, bioRxiv
• Financial data from SEC filings, earnings reports
• News monitoring and current events
• Domain-specific searches with source filtering

---

Contents API (POST /v1/contents)

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

Parameters

Summary Options

// Simple summary
summary: true

// Custom instructions
summary: "Extract key findings in bullet points"

// Structured extraction with JSON schema
summary: {
  type: "object",
  properties: {
    product_name: { type: "string" },
    price: { type: "number" },
    features: { type: "array", items: { type: "string" } }
  },
  required: ["product_name", "price"]
}

Response Structure

{
  "success": true,
  "tx_id": "tx_xyz789",
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com",
      "content": "Clean markdown content...",
      "description": "Meta description",
      "data_type": "unstructured",
      "length": 12840,
      "price": 0.002
    }
  ],
  "urls_requested": 1,
  "urls_processed": 1,
  "urls_failed": 0,
  "total_cost_dollars": 0.002
}

When to Use Contents

• Extracting article text for summarization
• Parsing documentation for RAG systems
• Cleaning web pages before LLM processing
• Batch URL-to-text conversion
• Structured data extraction from product pages

---

Answer API (POST /v1/answer)

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

Parameters

Structured Output Example

structured_output: {
  type: "object",
  properties: {
    summary: { type: "string" },
    key_points: { type: "array", items: { type: "string" } },
    confidence: { type: "number" }
  }
}

Response Structure

{
  "success": true,
  "tx_id": "tx_answer123",
  "original_query": "What is quantum computing?",
  "contents": "Quantum computing is a type of computation...",
  "data_type": "unstructured",
  "search_results": [...],
  "search_metadata": {
    "number_of_results": 8,
    "total_characters": 45000
  },
  "cost": {
    "total_deduction_dollars": 0.045,
    "search_deduction_dollars": 0.025,
    "ai_deduction_dollars": 0.020
  }
}

When to Use Answer

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

---

DeepResearch API

Async comprehensive research with detailed reports and citations.

Create Task (POST /v1/deepresearch/tasks)

Research Modes

Check Status (GET /v1/deepresearch/tasks/{id}/status)

Task Lifecycle

queued → running → completed/failed/cancelled

Create Response

{
  "success": true,
  "type": "deepresearch_create",
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "queued",
  "query": "AI market trends 2024",
  "model": "lite"
}

Status Response (Completed)

{
  "success": true,
  "type": "deepresearch_status",
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "completed",
  "query": "AI market trends 2024",
  "output": "# AI Market Trends 2024\n\n## Overview...",
  "pdf_url": "https://storage.valyu.ai/reports/...",
  "sources": [
    {
      "title": "Market Analysis 2024",
      "url": "https://example.com",
      "snippet": "Key findings...",
      "source": "web"
    }
  ],
  "progress": {
    "current_step": 5,
    "total_steps": 5
  },
  "usage": {
    "search_cost": 0.0075,
    "ai_cost": 0.15,
    "total_cost": 0.1575
  }
}

When to Use DeepResearch

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

---

Datasources API

Discover available data sources dynamically. Useful for AI agents to understand what data is available without loading all definitions into context.

List Datasources (GET /v1/datasources)

Returns all available datasources with metadata, pricing, and schemas.

Valid categories: research, healthcare, patents, markets, company, economic, predictions, transportation, legal, politics

Response Structure

{
  "success": true,
  "datasources": [
    {
      "id": "valyu/valyu-arxiv",
      "name": "Arxiv",
      "description": "Over 1 million pre-print research papers...",
      "category": "research",
      "type": "text",
      "modality": ["text", "image"],
      "topics": ["physics", "computer science", "mathematics"],
      "example_queries": ["transformer attention mechanism"],
      "pricing": { "cpm": 0.50 },
      "response_schema": {},
      "update_frequency": "daily",
      "size": 1000000,
      "coverage": {
        "start_date": "1991-01-01",
        "end_date": null
      }
    }
  ],
  "total_count": 25,
  "categories": {
    "research": { "name": "Research & Academic", "count": 4 },
    "markets": { "name": "Financial Markets", "count": 7 }
  }
}

List Categories (GET /v1/datasources/categories)

Returns all available categories with dataset counts.

Response Structure

{
  "success": true,
  "categories": [
    {
      "id": "research",
      "name": "Research & Academic",
      "description": "Academic papers and research publications",
      "dataset_count": 4
    },
    {
      "id": "markets",
      "name": "Financial Markets",
      "description": "Real-time and historical market data",
      "dataset_count": 7
    },
    {
      "id": "healthcare",
      "name": "Healthcare & Medical",
      "description": "Clinical trials, drug information, and health data",
      "dataset_count": 4
    }
  ]
}

When to Use Datasources API

• Discovering available data sources at runtime
• Building dynamic tool registries
• Cost estimation before search requests
• Understanding response schemas for structured extraction
• Filtering searches to specific datasets via included_sources

Example: Find and Use a Datasource

# 1. List available research datasources
curl -X GET "https://api.valyu.ai/v1/datasources?category=research" \
  -H "x-api-key: your_key"

# 2. Use discovered datasource ID in search
scripts/valyu search paper "quantum computing" 10
# This uses included_sources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", ...]

---

Error Codes

Choosing the Right API

Need to find information?
  └── Use Search API

Need to extract content from specific URLs?
  └── Use Contents API

Need an AI-synthesized answer with sources?
  └── Use Answer API

Need comprehensive research report?
  └── Use DeepResearch API

Need to discover available data sources?
  └── Use Datasources API

Content Extraction with Summary

Extract content with automatic or custom summarization.

Basic Summary

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

// Enable basic summary
const data = await valyu.contents({
  urls: ["https://example.com/article"],
  responseLength: "medium",
  extractEffort: "auto",
  summary: true
});

Custom Summary Instructions

const data = await valyu.contents({
  urls: ["https://example.com/research-paper"],
  responseLength: "large",
  extractEffort: "high",
  summary: "Summarize the methodology, key findings, and practical applications in 2-3 paragraphs"
});

from valyu import Valyu

valyu = Valyu()

# Custom summary
data = valyu.contents(
    urls=["https://example.com/research-paper"],
    response_length="large",
    extract_effort="high",
    summary="Summarize the methodology, key findings, and practical applications in 2-3 paragraphs"
)

print(data["results"][0]["content"])

CLI

# Basic summary
scripts/valyu contents "https://example.com" --summary

# Custom instructions
scripts/valyu contents "https://example.com" --summary "Key points in 3 bullets"

Basic Content Extraction

Turn any web page into clean, structured markdown data.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.contents({
  urls: ["https://techcrunch.com/category/artificial-intelligence/"],
  responseLength: "medium",  // "short", "medium", "large", "max"
  extractEffort: "auto"      // "auto", "normal", "high"
});

console.log(data.results[0].content);

from valyu import Valyu

valyu = Valyu()

data = valyu.contents(
    urls=["https://techcrunch.com/category/artificial-intelligence/"],
    response_length="medium",
    extract_effort="auto"
)

print(data["results"][0]["content"])

CLI

scripts/valyu contents "https://techcrunch.com/article"

Options

Extract Research Paper Data

Extract structured academic data from research papers.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.contents({
  urls: ["https://arxiv.org/abs/2301.00001"],
  responseLength: "max",
  extractEffort: "high",
  summary: {
    type: "object",
    properties: {
      title: { type: "string" },
      abstract: { type: "string" },
      methodology: { type: "string" },
      key_findings: {
        type: "array",
        items: { type: "string" }
      },
      limitations: { type: "string" }
    },
    required: ["title"]
  }
});

console.log(data.results[0].content);

from valyu import Valyu

valyu = Valyu()

data = valyu.contents(
    urls=["https://arxiv.org/abs/2301.00001"],
    response_length="max",
    extract_effort="high",
    summary={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "abstract": {"type": "string"},
            "methodology": {"type": "string"},
            "key_findings": {"type": "array", "items": {"type": "string"}},
            "limitations": {"type": "string"}
        },
        "required": ["title"]
    }
)

print(data["results"][0]["content"])

Extract Product Data

Extract structured product information from e-commerce pages.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.contents({
  urls: [
    "https://store.example.com/product-1",
    "https://store.example.com/product-2"
  ],
  extractEffort: "auto",
  summary: {
    type: "object",
    properties: {
      product_name: { type: "string" },
      features: {
        type: "array",
        items: { type: "string" }
      },
      pricing: { type: "string" },
      target_audience: { type: "string" }
    },
    required: ["product_name"]
  }
});

console.log(data.results[0].content);

from valyu import Valyu

valyu = Valyu()

data = valyu.contents(
    urls=["https://store.example.com/product"],
    extract_effort="auto",
    summary={
        "type": "object",
        "properties": {
            "product_name": {"type": "string"},
            "features": {"type": "array", "items": {"type": "string"}},
            "pricing": {"type": "string"},
            "target_audience": {"type": "string"}
        },
        "required": ["product_name"]
    }
)

print(data["results"][0]["content"])

CLI

scripts/valyu contents "https://amazon.com/product" --structured '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}'

News Aggregator

Build a news aggregator that extracts structured content from multiple sources.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.contents({
  urls: [
    "https://techcrunch.com/category/artificial-intelligence/",
    "https://venturebeat.com/category/entrepreneur/",
    "https://www.bbc.co.uk/news/technology"
  ],
  extractEffort: "auto",
  summary: {
    type: "object",
    properties: {
      headline: { type: "string" },
      summary_text: { type: "string" },
      category: { type: "string" },
      tags: {
        type: "array",
        items: { type: "string" },
        maxItems: 5
      }
    },
    required: ["headline", "summary_text"]
  }
});

data.results.forEach(result => {
  console.log(`Source: ${result.url}`);
  console.log(`Content: ${result.content}`);
});

from valyu import Valyu

valyu = Valyu()

data = valyu.contents(
    urls=[
        "https://techcrunch.com/category/artificial-intelligence/",
        "https://venturebeat.com/category/entrepreneur/",
        "https://www.bbc.co.uk/news/technology"
    ],
    extract_effort="auto",
    summary={
        "type": "object",
        "properties": {
            "headline": {"type": "string"},
            "summary_text": {"type": "string"},
            "category": {"type": "string"},
            "tags": {"type": "array", "items": {"type": "string"}, "maxItems": 5}
        },
        "required": ["headline", "summary_text"]
    }
)

for result in data["results"]:
    print(f"Source: {result['url']}")
    print(f"Content: {result['content']}")

Structured Content Extraction

Specify the structure of content extraction using JSON schemas.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const data = await valyu.contents({
  urls: ["https://store.example.com/product"],
  maxPriceDollars: 0.10,
  extractEffort: "auto",
  summary: {
    type: "object",
    properties: {
      product_name: { type: "string" },
      price: { type: "number", description: "Price in USD" },
      features: {
        type: "array",
        items: { type: "string" },
        maxItems: 5
      },
      availability: {
        type: "string",
        enum: ["in_stock", "out_of_stock", "preorder"]
      }
    },
    required: ["product_name", "price"]
  }
});

console.log(data.results[0].content);

from valyu import Valyu

valyu = Valyu()

data = valyu.contents(
    urls=["https://store.example.com/product"],
    max_price_dollars=0.10,
    extract_effort="auto",
    summary={
        "type": "object",
        "properties": {
            "product_name": {"type": "string"},
            "price": {"type": "number", "description": "Price in USD"},
            "features": {"type": "array", "items": {"type": "string"}, "maxItems": 5},
            "availability": {"type": "string", "enum": ["in_stock", "out_of_stock", "preorder"]}
        },
        "required": ["product_name", "price"]
    }
)

print(data["results"][0]["content"])

CLI

scripts/valyu contents "https://example.com" --structured '{
  "type": "object",
  "properties": {
    "title": {"type": "string"},
    "summary": {"type": "string"}
  }
}'

Data Coverage

Valyu's Search API provides access to millions of documents across academic, research, financial, healthcare, and other domains. We index both open-access repositories and premium proprietary sources.

All sources are continuously updated with real-time indexing and automated ingestion.

We also provide web search alongside these data sources for the latest news and information.

Want a source added? Contact us at team@valyu.ai.

Available Datasets

Below are the specific datasets available through Valyu. Use the included_sources parameter to target specific datasets, or let Valyu automatically select the most relevant sources for your query.

Research & Academic

Healthcare & Life Sciences

Financial Markets

Company Fundamentals

Economic Data

Prediction Markets

Transportation

Patents & IP

Domain Coverage Summary

Research Coverage

Coming Soon

---

Data coverage statistics updated daily. Contact us at [team@valyu.ai](mailto:team@valyu.ai) for specific domain requirements or custom data partnerships.

Fast Research Task

Use fast mode for quick answers, lightweight research, and simple lookups (~5 minutes).

Step 1: Create Task

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const task = await valyu.deepresearch.create({
  input: "What are the key differences between RAG and fine-tuning for LLMs?",
  model: "fast"
});

console.log(`Task created: ${task.deepresearch_id}`);
console.log(`Status: ${task.status}`);

Step 2: Wait for Completion

const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  pollInterval: 5000,    // Check every 5 seconds
  maxWaitTime: 600000    // Timeout after 10 minutes
});

if (result.status === "completed") {
  console.log("Research completed!");
  console.log(result.output);

  result.sources?.forEach(source => {
    console.log(`- ${source.title}: ${source.url}`);
  });

  console.log(`Total cost: $${result.usage?.total_cost.toFixed(4)}`);
}

from valyu import Valyu

valyu = Valyu()

# Create task
task = valyu.deepresearch.create(
    input="What are the key differences between RAG and fine-tuning for LLMs?",
    model="fast"
)

# Wait for completion
result = valyu.deepresearch.wait(
    task.deepresearch_id,
    poll_interval=5,
    max_wait_time=600
)

if result.status == "completed":
    print("Research completed!")
    print(result.output)
    print(f"Total cost: ${result.usage.total_cost:.4f}")

CLI

scripts/valyu deepresearch create "What are the key differences between RAG and fine-tuning?" --model fast
scripts/valyu deepresearch status <task-id>

Heavy Research Task

Use heavy mode for comprehensive, in-depth analysis (~90 minutes).

Step 1: Create Task

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const task = await valyu.deepresearch.create({
  input: "Analyze the competitive landscape of the cloud computing market in 2024",
  model: "heavy"
});

console.log(`Task created: ${task.deepresearch_id}`);
console.log(`Status: ${task.status}`);

Step 2: Wait for Completion

const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  pollInterval: 5000
});

if (result.status === "completed") {
  console.log("Research completed!");
  console.log(result.output);

  result.sources?.forEach(source => {
    console.log(`- ${source.title}: ${source.url}`);
  });

  console.log(`Total cost: $${result.usage?.total_cost.toFixed(4)}`);
}

from valyu import Valyu

valyu = Valyu()

# Create task
task = valyu.deepresearch.create(
    input="Analyze the competitive landscape of the cloud computing market in 2024",
    model="heavy"
)

# Wait for completion
result = valyu.deepresearch.wait(
    task.deepresearch_id,
    poll_interval=5
)

if result.status == "completed":
    print("Research completed!")
    print(result.output)
    for source in result.sources:
        print(f"- {source.title}: {source.url}")
    print(f"Total cost: ${result.usage.total_cost:.4f}")

CLI

scripts/valyu deepresearch create "Cloud computing market analysis 2024" --model heavy --pdf
scripts/valyu deepresearch status <task-id>

When to Use Heavy Mode

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

Lite Research Task

Use lite mode for balanced research (~10-20 minutes). Good for most use cases.

Step 1: Create Task

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const task = await valyu.deepresearch.create({
  input: "Comprehensive analysis of electric vehicle battery technology trends 2024",
  model: "lite"
});

console.log(`Task created: ${task.deepresearch_id}`);
console.log(`Status: ${task.status}`);

Step 2: Wait for Completion

const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  pollInterval: 5000,
  maxWaitTime: 1800000  // 30 minutes
});

if (result.status === "completed") {
  console.log("Research completed!");
  console.log(result.output);

  result.sources?.forEach(source => {
    console.log(`- ${source.title}: ${source.url}`);
  });

  console.log(`Total cost: $${result.usage?.total_cost.toFixed(4)}`);
}

from valyu import Valyu

valyu = Valyu()

# Create task
task = valyu.deepresearch.create(
    input="Comprehensive analysis of electric vehicle battery technology trends 2024",
    model="lite"
)

# Wait for completion
result = valyu.deepresearch.wait(
    task.deepresearch_id,
    poll_interval=5,
    max_wait_time=1800
)

if result.status == "completed":
    print("Research completed!")
    print(result.output)
    for source in result.sources:
        print(f"- {source.title}: {source.url}")
    print(f"Total cost: ${result.usage.total_cost:.4f}")

CLI

scripts/valyu deepresearch create "EV battery technology trends 2024" --model lite
scripts/valyu deepresearch status <task-id>

Valyu Design Philosophy

Core principles that guide Valyu's architecture and when to use it.

---

Core Principles

1. Built for AI

Valyu is designed for AI agents and LLMs, not adapted from a traditional search engine.

• Semantic understanding over keyword matching
• Structured JSON responses for machine consumption
• Embedding-powered retrieval for accuracy
• Focus on reducing hallucinations by grounding responses in real sources

2. One API, Many Sources

A unified interface consolidates multiple authoritative data sources:

• Real-time web content
• Academic papers and research
• Books and publications
• Financial data and filings
• Proprietary datasets

This eliminates the need to integrate multiple APIs separately.

3. Transparent Pricing

Pay-per-use CPM pricing with complete cost control:

• User-controlled spending limits (max_price)
• Relevance thresholds to filter low-quality results
• Source-specific cost variations
• No hidden fees or subscriptions

---

Ideal Use Cases

Valyu excels at:

• Retrieval-Augmented Generation (RAG) - Grounding LLM responses in real data
• AI Research Assistants - Powering knowledge-intensive workflows
• Knowledge Chatbots - Providing accurate, sourced answers
• Real-time Information - Current events, market data, news
• Specialized Domain Search - Academic, financial, medical, legal

---

Less Suitable Use Cases

Valyu is not designed for:

• Direct user-facing search (not a consumer search engine)
• Social media monitoring
• E-commerce product search
• Local business discovery
• Creative content generation

---

Implications for Agents

When deciding whether to use Valyu:

Anthropic Integration

Integrate Valyu's deep search capabilities directly into your Anthropic Claude applications using the provider system. This enables your AI agents to access real-time information from academic papers, news, financial data, and authoritative sources.

Installation

pip install valyu anthropic

Set your API keys:

export VALYU_API_KEY="your-valyu-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

Basic Usage

from anthropic import Anthropic
from valyu import AnthropicProvider
from dotenv import load_dotenv

load_dotenv()

# Initialize clients
anthropic_client = Anthropic()
provider = AnthropicProvider()

# Get Valyu tools
tools = provider.get_tools()

# Create a research request
messages = [
    {
        "role": "user",
        "content": "What are the latest developments in quantum computing? Write a summary of your findings."
    }
]

# Step 1: Call Anthropic with tools
response = anthropic_client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1000,
    tools=tools,
    messages=messages,
)

# Step 2: Execute tool calls
tool_results = provider.handle_tool_calls(response=response)

# Step 3: Get final response with search results
if tool_results:
    updated_messages = provider.build_conversation(messages, response, tool_results)
    final_response = anthropic_client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=2000,
        messages=updated_messages,
    )

    for content in final_response.content:
        if hasattr(content, "text"):
            print(content.text)

How It Works

The AnthropicProvider handles everything:

1. Tool Registration: Automatically formats Valyu search as an Anthropic tool 2. Tool Execution: Manages search API calls behind the scenes 3. Conversation Flow: Builds proper message sequences with tool results

Research Agent Example

from anthropic import Anthropic
from valyu import AnthropicProvider

def create_research_agent():
    client = Anthropic()
    provider = AnthropicProvider()
    tools = provider.get_tools()

    def research(query: str) -> str:
        system_prompt = """You are a research assistant with access to real-time information. Always cite your sources."""

        messages = [{"role": "user", "content": query}]

        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1000,
            tools=tools,
            messages=messages,
            system=system_prompt
        )

        tool_results = provider.handle_tool_calls(response=response)

        if tool_results:
            updated_messages = provider.build_conversation(messages, response, tool_results)
            final_response = client.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=2000,
                messages=updated_messages,
                system=system_prompt
            )

            result = ""
            for content in final_response.content:
                if hasattr(content, "text"):
                    result += content.text
            return result

        result = ""
        for content in response.content:
            if hasattr(content, "text"):
                result += content.text
        return result

    return research

# Usage
agent = create_research_agent()
result = agent("Find the price of Bitcoin and Nvidia over the last 2 years")
print(result)

Financial Analysis Example

def create_financial_agent():
    client = Anthropic()
    provider = AnthropicProvider()
    tools = provider.get_tools()

    def analyze_market(assets: list) -> str:
        query = f"Get the latest news and price data for {', '.join(assets)}, then provide a detailed market analysis report"

        messages = [{"role": "user", "content": query}]

        system_prompt = "You are a financial analyst. Provide data-driven insights with specific numbers and sources."

        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1000,
            tools=tools,
            messages=messages,
            system=system_prompt
        )

        tool_results = provider.handle_tool_calls(response=response)

        if tool_results:
            updated_messages = provider.build_conversation(messages, response, tool_results)
            final_response = client.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=2500,
                messages=updated_messages,
                system=system_prompt
            )

            result = ""
            for content in final_response.content:
                if hasattr(content, "text"):
                    result += content.text
            return result

        return ""

    return analyze_market

# Usage
financial_agent = create_financial_agent()
analysis = financial_agent(["Bitcoin", "Ethereum", "Tesla"])
print(analysis)

Model Selection

# For speed and efficiency
response = anthropic_client.messages.create(
    model="claude-3-5-haiku-20241022",  # Fastest
    max_tokens=1000,
    tools=tools,
    messages=messages,
)

# For balanced performance (recommended)
response = anthropic_client.messages.create(
    model="claude-sonnet-4-20250514",  # Best balance
    max_tokens=1500,
    tools=tools,
    messages=messages,
)

# For complex reasoning tasks
response = anthropic_client.messages.create(
    model="claude-3-opus-20240229",  # Most capable
    max_tokens=2000,
    tools=tools,
    messages=messages,
)

Search Parameters

Claude can automatically use advanced search parameters:

• max_num_results: Limit results (1-20, up to 100 with special API key)
• included_sources: Search specific domains or datasets
• excluded_sources: Exclude certain sources
• category: Guide search to specific topics
• start_date/end_date: Time-bounded searches
• relevance_threshold: Filter by relevance (0-1)

Best Practices

Use System Prompts

system_prompt = """You are a research assistant with access to real-time information.

Guidelines:
- Always cite sources from search results
- Provide specific data points and numbers
- If information is recent, mention the date
- Do not use search operators (site:, OR, AND, quotes). Use natural keyword queries.
"""

API Reference

AnthropicProvider

class AnthropicProvider:
    def __init__(self, valyu_api_key: Optional[str] = None):
        """Initialize provider. API key auto-detected from environment if not provided."""

    def get_tools(self) -> List[Dict]:
        """Get list of tools formatted for Anthropic Messages API."""

    def handle_tool_calls(self, response, modifiers=None) -> List[Dict]:
        """Execute tool calls from Anthropic response."""

    def build_conversation(self, input_messages, response, tool_results) -> List[Dict]:
        """Build updated message list with tool results."""

Resources

• Anthropic API Docs - Official documentation
• Valyu API Reference - Complete API documentation
• Python SDK - Full SDK documentation
• Get API Key - Sign up for free $10 credit

AWS Bedrock AgentCore Integration

Combine Valyu's real-time search capabilities with AWS Bedrock AgentCore for secure, scalable, and auditable AI agent deployments.

Build sophisticated AI agents that can search financial data, academic papers, SEC filings, patents, and more with enterprise-grade security, OAuth authentication, and CloudTrail audit logging.

Why AWS Bedrock AgentCore + Valyu?

• 7 Specialized Search Tools: Financial data, SEC filings, academic papers, patents, biomedical research, web search, and economic indicators
• Enterprise Security: OAuth 2.0 authentication, Cognito integration, IAM policies, and CloudTrail audit logging
• Production Infrastructure: Deploy to AWS with managed scaling, monitoring, and high availability
• Simple Integration: Works with Strands Agents out of the box

Available Search Tools

Quick Start

Installation

# For local development with Strands Agents
pip install "valyu-agentcore[strands]"

# For AWS AgentCore Gateway/Runtime deployment
pip install "valyu-agentcore[agentcore]"

Environment Setup

export VALYU_API_KEY="your-valyu-api-key"
export AWS_REGION="us-east-1"  # Optional, defaults to us-east-1

Your First Agent

from valyu_agentcore import webSearch
from strands import Agent
from strands.models import BedrockModel

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=[webSearch()],
)

response = agent("What are the latest developments in quantum computing?")
print(response)

Multi-Tool Agent

from valyu_agentcore import webSearch, financeSearch, secSearch, paperSearch
from strands import Agent
from strands.models import BedrockModel

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=[
        webSearch(),
        financeSearch(),
        secSearch(),
        paperSearch(),
    ],
)

response = agent("Analyze NVIDIA's competitive position in the AI chip market")
print(response)

Using Tool Groups

from valyu_agentcore import ValyuTools
from strands import Agent
from strands.models import BedrockModel

tools = ValyuTools(max_num_results=5)

# Financial analysis agent
financial_agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=tools.financial_tools(),  # Includes: financeSearch, secSearch, economicsSearch
)

# Research agent
research_agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=tools.research_tools(),  # Includes: paperSearch, bioSearch, patentSearch
)

# All tools
complete_agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=tools.all(),  # All 7 search tools
)

Deployment Options

Option 1: Local Development

Best for prototyping and testing.

from valyu_agentcore import webSearch
from strands import Agent
from strands.models import BedrockModel

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0"),
    tools=[webSearch()],
)

Option 2: AgentCore Gateway (Recommended for Production)

Enterprise-grade deployment with OAuth authentication, centralized API key management, and CloudTrail logging.

from valyu_agentcore.gateway import setup_valyu_gateway, GatewayAgent

config = setup_valyu_gateway()
print(f"Gateway URL: {config.gateway_url}")

with GatewayAgent.from_config() as agent:
    response = agent("Search for NVIDIA SEC filings")
    print(response)

Option 3: AgentCore Runtime

Full AWS-managed deployment with auto-scaling, streaming, and lifecycle management.

cd examples/runtime
agentcore configure --entrypoint agent.py --non-interactive --name valyuagent
agentcore launch
agentcore invoke '{"prompt": "What is NVIDIA stock price?"}'

Tool Configuration

from valyu_agentcore import financeSearch

tool = financeSearch(
    api_key="val_xxx",
    search_type="all",
    max_num_results=10,
    max_price=0.50,
    relevance_threshold=0.7,
    excluded_sources=["reddit.com"],
    included_sources=["reuters.com"],
    category="quarterly earnings",
)

Resources

• GitHub: Source code, examples, and CloudFormation templates
• AWS Bedrock AgentCore: Official AWS documentation
• Strands Agents: Framework documentation
• Get API Key: Sign up for free $10 credit at platform.valyu.ai

Claude Agent SDK Integration

This is a community-maintained integration developed by GhouI.

The Valyu Claude Agent SDK integration enables AI agents built with Anthropic's Claude Agent SDK to access real-time web data and specialized knowledge bases through powerful search capabilities using the Model Context Protocol (MCP).

Available Search Tools

• Web Search: Real-time information, news, and current events
• Finance Search: Stock prices, earnings reports, SEC filings, and financial metrics
• Paper Search: Academic research from arXiv and scholarly databases
• Bio Search: Biomedical literature, PubMed articles, and clinical trials
• Patent Search: Patent databases and prior art research
• SEC Search: Regulatory documents (10-K, 10-Q, 8-K filings)
• Economics Search: Labor statistics, Federal Reserve data, World Bank indicators
• Company Research: Comprehensive intelligence reports with synthesized data

Installation

git clone https://github.com/GhouI/valyu-claude-agent-sdk.git
cd valyu-claude-agent-sdk
npm install --legacy-peer-deps

Configure credentials in .env:

VALYU_API_KEY=your-valyu-api-key-here

Basic Usage

Web Search Example

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuWebSearchServer } from "./tools/index.js";

async function webSearchExample() {
  for await (const message of query({
    prompt: "What are the latest developments in AI technology?",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-web-search__web_search"],
      mcpServers: {
        "valyu-web-search": valyuWebSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await webSearchExample();

Finance Search Example

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuFinanceSearchServer } from "./tools/index.js";

async function financeSearchExample() {
  for await (const message of query({
    prompt: "What is the current stock price of NVIDIA and their recent earnings?",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-finance-search__finance_search"],
      mcpServers: {
        "valyu-finance-search": valyuFinanceSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

Company Research Example

import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuCompanyResearchServer } from "./tools/index.js";

async function companyResearchExample() {
  for await (const message of query({
    prompt: "Give me a comprehensive report on OpenAI including leadership, products, and funding",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-company-research__company_research"],
      mcpServers: {
        "valyu-company-research": valyuCompanyResearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

Multi-Tool Agent

import { query } from "@anthropic-ai/claude-agent-sdk";
import {
  valyuWebSearchServer,
  valyuFinanceSearchServer,
  valyuPaperSearchServer,
} from "./tools/index.js";

async function multiToolAgent() {
  for await (const message of query({
    prompt: "Research the impact of AI on financial markets, including recent news and academic papers",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: [
        "mcp__valyu-web-search__web_search",
        "mcp__valyu-finance-search__finance_search",
        "mcp__valyu-paper-search__paper_search",
      ],
      mcpServers: {
        "valyu-web-search": valyuWebSearchServer,
        "valyu-finance-search": valyuFinanceSearchServer,
        "valyu-paper-search": valyuPaperSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

Custom Bio Search Parameters

import { query } from "@anthropic-ai/claude-agent-sdk";
import { createBioSearchServer } from "./tools/index.js";

const customBioSearchServer = createBioSearchServer({
  searchType: "proprietary",
  maxNumResults: 10,
  includedSources: ["pubmed", "clinicaltrials.gov"],
  maxPrice: 30.0,
  relevanceThreshold: 0.7,
  category: "biomedical",
});

for await (const message of query({
  prompt: "Find clinical trials for CRISPR gene therapy",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: ["mcp__valyu-bio-search__bio_search"],
    mcpServers: {
      "valyu-bio-search": customBioSearchServer,
    },
  },
})) {
  // Handle messages
}

MCP Tool Identifiers

mcp__valyu-web-search__web_search
mcp__valyu-finance-search__finance_search
mcp__valyu-paper-search__paper_search
mcp__valyu-bio-search__bio_search
mcp__valyu-patent-search__patent_search
mcp__valyu-sec-search__sec_search
mcp__valyu-economics-search__economics_search
mcp__valyu-company-research__company_research

Best Practices

Choose the Right Search Tool

// Use finance search for financial data
const financeResults = await query({
  prompt: "What is Apple's stock price?",
  options: {
    allowedTools: ["mcp__valyu-finance-search__finance_search"],
    mcpServers: { "valyu-finance-search": valyuFinanceSearchServer },
  },
});

Cost Optimization

const quickSearch = createBioSearchServer({
  maxNumResults: 3,
  maxPrice: 15.0,
  relevanceThreshold: 0.6,
});

const deepSearch = createBioSearchServer({
  maxNumResults: 20,
  maxPrice: 50.0,
  relevanceThreshold: 0.5,
});

Resources

• GitHub Repository - Source code
• API Reference - Complete Valyu API documentation
• Claude Agent SDK - Official Anthropic SDK
• Get API Key - Sign up for free $10 credit

Claude Code Plugin Integration

The Valyu Search Plugin for Claude Code provides direct access to Valyu's search APIs through a CLI interface. This community-maintained tool (developed by GhouI) enables Claude Code to perform real-time searches across multiple data sources.

Key Features

• Zero Dependencies: Uses Node.js built-in fetch for direct API calls
• 8 Search Types: Web, finance, academic, biomedical, patents, SEC filings, economics, and news
• AI-Powered Answers: Returns results with source citations
• Content Extraction: Extracts clean content from any URL
• Deep Research: Asynchronous research reports for complex topics

Installation

/plugin marketplace add valyu-network/valyu-search-plugin
/plugin install valyu-search-plugin@valyu-marketplace

API Key Setup

Get your free API key at platform.valyu.ai ($10 credit included).

Automatic Setup (Recommended)

Claude detects missing configuration on first use and prompts you to paste your API key, then saves it to ~/.valyu/config.json automatically.

Manual Setup Options

Environment Variable (Zsh):

echo 'export VALYU_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Config File:

mkdir -p ~/.valyu
echo '{"apiKey": "your-api-key-here"}' > ~/.valyu/config.json

VSCode Settings:

Add to settings.json:

{
  "terminal.integrated.env.osx": {
    "VALYU_API_KEY": "your-api-key-here"
  }
}

Usage Syntax

Natural Language: "Search the web for AI developments in 2025"

Structured Syntax: Valyu(searchType, "query", maxResults)

Search Types

Example Commands

Valyu(web, "AI developments 2025", 10)
Valyu(finance, "Apple Q4 2024 earnings", 8)
Valyu(paper, "transformer neural networks", 15)
Valyu(answer, "What is quantum computing?")
Valyu(contents, "https://example.com/article")
Valyu(deepresearch, create, "AI market trends 2025")
Valyu(deepresearch, status, "task-id-here")

Output Format

Results return as structured JSON with success, type, searchType, query, resultCount, results array, and cost.

Requirements

• Node.js 18+
• Valyu API key (free tier available)

Support Resources

• GitHub: github.com/valyu-network/claude-search-plugin
• Discord: discord.gg/umtmSsppRY
• API Documentation: docs.valyu.ai

Google Gemini Integration

Valyu provides seamless integration with the Google Gemini API through function calling, enabling your Gemini models to access proprietary data sources, real-time web search, academic data sources, and financial data.

Installation

pip install google-generativeai requests

Set your API keys:

export GOOGLE_API_KEY="your-google-api-key"
export VALYU_API_KEY="your-valyu-api-key"

Basic Integration

Function Definition

import google.generativeai as genai
import requests
import json
import os
from typing import Literal

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])

def valyu_search(
    query: str,
    search_type: Literal["all", "web", "proprietary", "news"] = "all",
    max_num_results: int = 5,
    relevance_threshold: float = 0.5,
    max_price: float = 30.0,
    category: str = None
) -> str:
    """Search for information using Valyu's comprehensive knowledge base."""
    url = "https://api.valyu.ai/v1/search"

    payload = {
        "query": query,
        "search_type": search_type,
        "max_num_results": max_num_results,
        "relevance_threshold": relevance_threshold,
        "max_price": max_price,
        "is_tool_call": True
    }

    if category:
        payload["category"] = category

    headers = {
        "Authorization": f"Bearer {os.environ['VALYU_API_KEY']}",
        "Content-Type": "application/json"
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
    except Exception as e:
        return f"Search error: {str(e)}"

# Define the function declaration for Gemini
valyu_function_declaration = genai.protos.FunctionDeclaration(
    name="valyu_search",
    description="Search for real-time information, academic papers, and comprehensive knowledge using Valyu's database",
    parameters=genai.protos.Schema(
        type=genai.protos.Type.OBJECT,
        properties={
            "query": genai.protos.Schema(
                type=genai.protos.Type.STRING,
                description="Natural language search query"
            ),
            "search_type": genai.protos.Schema(
                type=genai.protos.Type.STRING,
                enum=["all", "web", "proprietary", "news"],
                description="Type of search"
            ),
            "max_num_results": genai.protos.Schema(
                type=genai.protos.Type.INTEGER,
                description="Number of results to return (1-20)"
            ),
            "relevance_threshold": genai.protos.Schema(
                type=genai.protos.Type.NUMBER,
                description="Minimum relevance score (0.0-1.0)"
            ),
            "max_price": genai.protos.Schema(
                type=genai.protos.Type.NUMBER,
                description="Maximum cost in dollars"
            ),
            "category": genai.protos.Schema(
                type=genai.protos.Type.STRING,
                description="Natural language category to guide search"
            )
        },
        required=["query"]
    )
)

valyu_tool = genai.protos.Tool(function_declarations=[valyu_function_declaration])

model = genai.GenerativeModel(
    model_name="gemini-2.0-flash-exp",
    tools=[valyu_tool]
)

Basic Usage

def chat_with_search(user_message: str):
    chat = model.start_chat()

    response = chat.send_message(
        f"You are a helpful assistant with access to real-time search. "
        f"Use the valyu_search function to find current information when needed. "
        f"User query: {user_message}"
    )

    if response.candidates[0].content.parts:
        for part in response.candidates[0].content.parts:
            if hasattr(part, 'function_call') and part.function_call:
                function_call = part.function_call

                if function_call.name == "valyu_search":
                    function_args = {}
                    for key, value in function_call.args.items():
                        function_args[key] = value

                    search_results = valyu_search(**function_args)

                    function_response = genai.protos.Part(
                        function_response=genai.protos.FunctionResponse(
                            name="valyu_search",
                            response={"result": search_results}
                        )
                    )

                    final_response = chat.send_message(function_response)
                    return final_response.text

    return response.text

# Example
result = chat_with_search("What are the latest developments in quantum computing?")
print(result)

Multi-Turn Conversations

class GeminiConversationWithSearch:
    def __init__(self):
        self.chat = model.start_chat()
        self.system_prompt = "You are a helpful research assistant with access to real-time search."

    def send_message(self, user_message: str):
        full_message = f"{self.system_prompt}\n\nUser: {user_message}"

        response = self.chat.send_message(full_message)

        if response.candidates[0].content.parts:
            for part in response.candidates[0].content.parts:
                if hasattr(part, 'function_call') and part.function_call:
                    function_call = part.function_call

                    if function_call.name == "valyu_search":
                        function_args = {}
                        for key, value in function_call.args.items():
                            function_args[key] = value

                        search_results = valyu_search(**function_args)

                        function_response = genai.protos.Part(
                            function_response=genai.protos.FunctionResponse(
                                name="valyu_search",
                                response={"result": search_results}
                            )
                        )

                        final_response = self.chat.send_message(function_response)
                        return final_response.text

        return response.text

# Usage
conversation = GeminiConversationWithSearch()
response1 = conversation.send_message("What are the latest developments in renewable energy?")
print(response1)

response2 = conversation.send_message("How do these compare to last year's progress?")
print(response2)

Specialized Use Cases

Financial Analysis Assistant

def financial_analysis_gemini(query: str):
    financial_model = genai.GenerativeModel(
        model_name="gemini-2.0-flash-exp",
        tools=[valyu_tool],
        system_instruction="""You are a financial analyst with access to real-time market data and academic research.
        Use valyu_search with search_type='web' for current market news and
        search_type='proprietary' for academic financial research. Always provide data-driven insights."""
    )

    chat = financial_model.start_chat()
    response = chat.send_message(query)

    return process_gemini_response_with_functions(chat, response)

Academic Research Assistant

def academic_research_gemini(research_question: str):
    academic_model = genai.GenerativeModel(
        model_name="gemini-2.0-flash-exp",
        tools=[valyu_tool],
        system_instruction="""You are an academic research assistant. Focus on peer-reviewed sources and provide proper citations.
        Use the search tool to find relevant academic papers and synthesize the findings."""
    )

    chat = academic_model.start_chat()
    response = chat.send_message(research_question)

    return process_gemini_response_with_functions(chat, response)

Gemini Models

Available Gemini 2.0 models:

• `gemini-2.0-flash-exp`: Latest experimental model with enhanced capabilities
• `gemini-2.0-flash-thinking-exp`: Model with enhanced reasoning capabilities
• `gemini-1.5-pro`: Production-ready model for complex tasks
• `gemini-1.5-flash`: Fast model for quick responses

API Reference

Function Parameters

• `query` (required): Natural language search query
• `search_type`: "all", "web", "proprietary", or "news" (default: "all")
• `max_num_results`: 1-20 results (default: 5)
• `relevance_threshold`: 0.0-1.0 relevance filter (default: 0.5)
• `max_price`: Maximum cost in CPM
• `category`: Natural language context guide

Resources

• Gemini Function Calling - Official documentation
• Valyu API Reference - Complete API documentation
• Gemini Models - Model capabilities
• Get API Key - Sign up for free $10 credit

LangChain Integration

Valyu integrates seamlessly with LangChain as a search tool, allowing you to enhance your AI agents and RAG applications with real-time web search and proprietary data sources.

The package includes two main tools:

• `ValyuSearchTool`: Deep search operations with comprehensive parameter control
• `ValyuContentsTool`: Extract clean content from specific URLs

Installation

pip install -U langchain-valyu

Configure credentials:

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

For agent examples:

export ANTHROPIC_API_KEY="your-anthropic-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Basic Usage

ValyuSearchTool for Deep Search

import os
from langchain_valyu import ValyuSearchTool

os.environ["VALYU_API_KEY"] = "your-api-key-here"

tool = ValyuSearchTool()

search_results = tool._run(
    query="What are agentic search-enhanced large reasoning models?",
    search_type="all",
    max_num_results=5,
    relevance_threshold=0.5,
    max_price=30.0
)

print("Search Results:", search_results.results)

ValyuContentsTool for Content Extraction

from langchain_valyu import ValyuContentsTool

contents_tool = ValyuContentsTool()

urls = [
    "https://arxiv.org/abs/2301.00001",
    "https://example.com/article",
]

extracted_content = contents_tool._run(urls=urls)

for result in extracted_content.results:
    print(f"URL: {result['url']}")
    print(f"Title: {result['title']}")
    print(f"Content: {result['content'][:200]}...")

Using with LangChain Agents

pip install langchain-anthropic langgraph

import os
from langchain_valyu import ValyuSearchTool
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import HumanMessage

os.environ["VALYU_API_KEY"] = "your-valyu-api-key"
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"

llm = ChatAnthropic(model="claude-sonnet-4-20250514")
valyu_search_tool = ValyuSearchTool()

agent = create_react_agent(llm, [valyu_search_tool])

user_input = "What are the key factors driving recent stock market volatility?"

for step in agent.stream(
    {"messages": [HumanMessage(content=user_input)]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()

Advanced Configuration

Search Parameters

results = tool._run(
    query="quantum computing breakthroughs 2024",
    search_type="proprietary",
    max_num_results=10,
    relevance_threshold=0.6,
    max_price=30.0,
    is_tool_call=True,
    start_date="2024-01-01",
    end_date="2024-12-31",
    included_sources=["arxiv.org", "nature.com"],
    excluded_sources=["reddit.com"],
    response_length="medium",
    country_code="US",
    fast_mode=False,
)

Source Filtering

# Include only academic sources
academic_results = tool._run(
    query="machine learning research 2024",
    search_type="proprietary",
    included_sources=["arxiv.org", "pubmed.ncbi.nlm.nih.gov", "ieee.org"],
    max_num_results=8
)

# Exclude social media
filtered_results = tool._run(
    query="AI policy developments",
    search_type="web",
    excluded_sources=["reddit.com", "twitter.com", "facebook.com"],
    max_num_results=10
)

Example: Financial Research Assistant

from langchain_valyu import ValyuSearchTool
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import HumanMessage, SystemMessage

financial_llm = ChatAnthropic(model="claude-sonnet-4-20250514")
valyu_tool = ValyuSearchTool()

financial_agent = create_react_agent(financial_llm, [valyu_tool])

query = "What are the latest developments in cryptocurrency regulation?"

system_context = SystemMessage(content="""You are a financial research assistant. Use Valyu to search for:
- Real-time market data and news
- Academic research on financial models
- Economic indicators and analysis

Always cite your sources and provide context about data recency.""")

for step in financial_agent.stream(
    {"messages": [system_context, HumanMessage(content=query)]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()

API Reference

ValyuSearchTool Parameters

• `query` (required): Natural language search query
• `search_type`: "all", "web", "proprietary", or "news" (default: "all")
• `max_num_results`: 1-20 results (default: 5)
• `relevance_threshold`: 0.0-1.0 relevance score (default: 0.5)
• `max_price`: Maximum cost in CPM
• `is_tool_call`: Optimize for LLM consumption (default: true)
• `start_date`/`end_date`: Time filtering (YYYY-MM-DD)
• `included_sources`/`excluded_sources`: URL/domain filtering
• `response_length`: "short", "medium", "large", "max"
• `country_code`: 2-letter ISO country code
• `fast_mode`: Enable for faster results (default: false)

ValyuContentsTool Parameters

• `urls` (required): List of URLs to extract (max 10 per request)

Resources

• LangChain Valyu Tool - Official documentation
• API Reference - Complete Valyu API documentation
• Get API Key - Sign up for free $10 credit

LlamaIndex Integration

Valyu integrates seamlessly with LlamaIndex as a comprehensive tool spec, allowing you to enhance your AI agents and RAG applications with real-time web search and proprietary data sources.

The package includes two main functions:

• `search()`: Deep search operations with comprehensive parameter control
• `get_contents()`: Extract clean content from specific URLs

Installation

pip install llama-index-tools-valyu

Configure credentials:

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

Basic Usage

ValyuToolSpec for Deep Search

import os
from llama_index.tools.valyu import ValyuToolSpec

os.environ["VALYU_API_KEY"] = "your-api-key-here"

valyu_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    verbose=True,
    max_price=100,
    relevance_threshold=0.5,
    fast_mode=False,
)

search_results = valyu_tool.search(
    query="What are agentic search-enhanced large reasoning models?",
    search_type="all",
    max_num_results=5,
)

for doc in search_results:
    print(f"Title: {doc.metadata['title']}")
    print(f"Content: {doc.text[:200]}...")
    print(f"Source: {doc.metadata['url']}")
    print(f"Relevance: {doc.metadata['relevance_score']}")

ValyuToolSpec for Content Extraction

valyu_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    verbose=True,
    contents_summary=True,
    contents_extract_effort="high",
    contents_response_length="medium",
)

urls = [
    "https://arxiv.org/abs/1706.03762",
    "https://en.wikipedia.org/wiki/Transformer_(machine_learning_model)"
]

content_results = valyu_tool.get_contents(urls=urls)

for doc in content_results:
    print(f"URL: {doc.metadata['url']}")
    print(f"Title: {doc.metadata['title']}")
    print(f"Content: {doc.text[:300]}...")

Using with LlamaIndex OpenAI Agents

import os
from llama_index.agent.openai import OpenAIAgent
from llama_index.tools.valyu import ValyuToolSpec

os.environ["VALYU_API_KEY"] = "your-valyu-api-key"
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

valyu_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    max_price=100,
    fast_mode=True,
    contents_summary=True,
    contents_extract_effort="normal",
    contents_response_length="medium",
)

agent = OpenAIAgent.from_tools(
    valyu_tool.to_tool_list(),
    verbose=True,
)

search_response = agent.chat(
    "What are the key considerations for implementing statistical arbitrage strategies?"
)
print(search_response)

Advanced Configuration

Comprehensive Parameter Configuration

valyu_tool = ValyuToolSpec(
    api_key="your-api-key",
    verbose=True,
    max_price=100,
    relevance_threshold=0.5,
    fast_mode=False,
    included_sources=["arxiv.org", "pubmed.ncbi.nlm.nih.gov"],
    excluded_sources=["reddit.com", "twitter.com"],
    response_length="medium",
    country_code="US",
    contents_summary=True,
    contents_extract_effort="high",
    contents_response_length="large",
)

results = valyu_tool.search(
    query="quantum computing breakthroughs 2024",
    search_type="all",
    max_num_results=10,
    start_date="2024-01-01",
    end_date="2024-12-31",
)

Source Filtering Examples

# Academic-focused configuration
academic_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    included_sources=[
        "arxiv.org",
        "pubmed.ncbi.nlm.nih.gov",
        "ieee.org",
        "nature.com",
        "sciencedirect.com"
    ],
    response_length="large",
    relevance_threshold=0.7
)

# News and current events configuration
news_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    excluded_sources=["reddit.com", "twitter.com", "facebook.com"],
    fast_mode=True,
    country_code="US",
    response_length="short"
)

Example: Financial Research Assistant

from llama_index.agent.openai import OpenAIAgent
from llama_index.tools.valyu import ValyuToolSpec

financial_tool = ValyuToolSpec(
    api_key=os.environ["VALYU_API_KEY"],
    max_price=100,
    fast_mode=True,
    excluded_sources=["reddit.com", "twitter.com"],
    response_length="medium",
    country_code="US",
    contents_summary=True,
    contents_extract_effort="high",
    contents_response_length="large"
)

financial_agent = OpenAIAgent.from_tools(
    financial_tool.to_tool_list(),
    verbose=True,
    system_prompt="""You are a financial research assistant. Use Valyu to search for:
    - Real-time market data and news
    - Academic research on financial models
    - Economic indicators and analysis

    Always cite your sources and provide context about data recency."""
)

response = financial_agent.chat(
    "What are the latest developments in cryptocurrency regulation?"
)
print(response)

API Reference

ValyuToolSpec Initialization Parameters

• `api_key` (required): Valyu API key
• `verbose`: Enable verbose logging (default: False)
• `max_price`: Maximum cost in dollars for search operations
• `relevance_threshold`: Minimum relevance score 0.0-1.0 (default: 0.5)
• `fast_mode`: Enable fast mode for faster results (default: False)
• `included_sources`: List of URLs/domains to include
• `excluded_sources`: List of URLs/domains to exclude
• `response_length`: "short", "medium", "large", "max"
• `country_code`: 2-letter ISO country code
• `contents_summary`: AI summary config (bool, str, or dict)
• `contents_extract_effort`: "normal", "high", or "auto"
• `contents_response_length`: Content length per URL

search() Method Parameters

• `query` (required): Natural language search query
• `search_type`: "all", "web", "proprietary", or "news" (default: "all")
• `max_num_results`: 1-20 results (default: 5)
• `start_date`/`end_date`: Time filtering (YYYY-MM-DD)
• `fast_mode`: Override tool default

get_contents() Method Parameters

• `urls` (required): List of URLs to extract (max 10 per request)

Resources

• LlamaIndex Valyu Tool - LlamaHub documentation
• API Reference - Complete Valyu API documentation
• Get API Key - Sign up for free $10 credit

LM Studio Plugin Integration

The Valyu plugin enhances local LLMs in LM Studio by enabling real-time web search and webpage content extraction capabilities directly within the application.

Setup Instructions

1. Installation

Install the plugin directly from the LM Studio Hub at https://lmstudio.ai/valyu/valyu

2. API Key Setup

• Sign up for a free account at https://platform.valyu.ai
• Receive $10 in initial credit
• Paste your API key into the plugin settings within LM Studio

3. Configuration

Open the plugin settings and add your API key to activate the search functionality.

Available Tools

The plugin provides two primary tools for LLM interactions:

valyu_deepsearch: Enables web searches to retrieve current information across multiple sources

valyu_contents: Extracts and processes text content from specified URLs

Usage Examples

Users can pose natural language questions such as:

• "What's the latest news about quantum computing?"
• "Find recent research on transformer models"
• "Get Tesla's current stock price"

Model Compatibility

Recommended Model Families:

• Qwen (excellent tool calling support)
• Gemma (reliable tool execution)
• Granite (strong performance)

Important Note: Models under 7B parameters frequently struggle with tool calling and may enter loops by repeatedly invoking search tools.

Troubleshooting

Common Issues:

• Verify API key accuracy
• Use larger models (7B+)
• Select from recommended model families
• Switch to more capable models if tools are called repeatedly

Support

For assistance, join the community Discord at https://discord.gg/umtmSsppRY

Local MCP Integration

The Valyu MCP Server is a Model Context Protocol tool enabling AI models to retrieve high-quality context from Valyu's API across multiple sources including proprietary datasets, Wikipedia, arXiv, PubMed, financial data, and web search.

Prerequisites

• Python 3.10 or higher
• Claude Desktop (latest version)
• Valyu API Key from https://platform.valyu.ai

Verify Python installation: python --version

Setup Instructions

1. Clone and Configure Environment

git clone https://github.com/valyu-network/valyu-mcp.git
cd valyu-mcp

Create virtual environment (macOS/Linux):

python -m venv .venv
source .venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

2. Configure Environment Variables

Create .env file with your API credentials:

echo "VALYU_API_KEY=your-api-key-here" > .env

3. Configure Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "valyu-mcp": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/python",
      "args": ["-u", "/ABSOLUTE/PATH/TO/valyu-mcp.py"],
      "env": {
        "VALYU_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace paths with absolute paths to your virtual environment and script.

Testing

After restarting Claude Desktop:

1. Look for Tools Icon - A hammer icon appears when the MCP server runs successfully 2. Inspect Available Tools - Click hammer icon to verify "valyu-mcp" is listed 3. Try Example Queries - Test with queries like "What are the latest advancements in topological quantum computing"

Claude will indicate "Making a tool request: valyu-mcp" and fetch context from the API.

Monitoring Logs

macOS:

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

Windows:

Get-Content $env:APPDATA\Claude\Logs\mcp_valyu-mcp.log -Wait

Access logs through Claude Desktop: Settings > Developer > Open Logs Folder.

Troubleshooting

Resources

• Platform: https://platform.valyu.ai (Get API key and free credits)
• Documentation: https://docs.valyu.ai
• GitHub: https://github.com/valyu-network/valyu-mcp

Remote MCP Integration

Valyu's Remote MCP enables AI assistants like Claude to perform real-time searches across academic papers, web content, and financial data without local server setup.

Quick Setup

MCP Server URL:

https://mcp.valyu.ai/mcp?valyuApiKey=your-valyu-api-key

Get your API key at platform.valyu.ai.

Configuration Methods

Claude Desktop

Add to your configuration file:

{
  "mcpServers": {
    "valyu": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.valyu.ai/mcp?valyuApiKey=your-valyu-api-key"
      ]
    }
  }
}

Claude Code CLI

claude mcp add --transport http valyuMcp "https://mcp.valyu.ai/mcp?valyuApiKey=YOUR_API_KEY"

OpenAI Responses API (Python)

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
  model="gpt-5",
  input=[],
  text={"format": {"type": "text"}},
  reasoning={},
  tools=[
    {
      "type": "mcp",
      "server_label": "Valyu",
      "server_url": "https://mcp.valyu.ai/mcp?valyuApiKey=VALYU_API_KEY",
      "allowed_tools": [
        "valyu_search",
        "valyu_academic_search",
        "valyu_financial_search",
        "valyu_sec_search",
        "valyu_company_research",
        "valyu_patents",
        "valyu_bio_search",
        "valyu_economics_search",
        "valyu_contents",
        "valyu_datasources",
        "valyu_datasources_categories"
      ],
      "require_approval": "always"
    }
  ],
  temperature=1,
  max_output_tokens=2048,
  top_p=1,
  store=True
)

Available Tools

Key Features

• 11 specialized tools spanning research, finance, healthcare, and economics
• Parallel execution: Company research completes 4x faster than sequential queries
• Real-time data: Live stock prices, crypto rates, insider trading
• Full-text search: Complete academic papers and SEC documents
• 36+ integrated datasets across multiple domains
• HTTP/SSE transport for OpenAI Responses API compatibility

Cost Control

Limit spending per search:

https://mcp.valyu.ai/mcp?valyuApiKey=your-key&maxPrice=50

Recommended range: 30-100 CPM ($0.03-$0.10) for most use cases.

Resources

• Platform: platform.valyu.ai
• Docs: docs.valyu.ai
• GitHub: github.com/valyu-network

n8n Integration

Valyu offers a community node for n8n that brings AI-powered search, extraction, and research capabilities into workflow automation. The integration is available exclusively on self-hosted n8n instances.

Core Capabilities

The Valyu node provides four main operations:

Search: Search across the web and premium data sources (academic papers, financial data, news) with customizable filters for search type, results count, response length, and date ranges.

Extraction: Pull clean content from webpages with optional AI summarization. Supports raw text extraction, auto-summaries, custom prompts, or structured JSON output.

Answer: Generate instant AI-powered answers to questions, backed by real search results for quick Q&A and chatbot applications.

Deep Research: Comprehensive multi-source research producing detailed reports in 10-30 minutes depending on complexity mode selected.

Installation & Setup

Prerequisites

• Self-hosted n8n instance (not available on n8n Cloud)
• Free Valyu account at platform.valyu.ai
• API key from Valyu dashboard

Installation Steps

1. Navigate to Settings > Community Nodes > Install 2. Enter package name: n8n-nodes-valyu 3. Accept community node risks and confirm installation

Credential Configuration

1. Add Valyu node to canvas 2. Create new credential with:

• API Key: Your Valyu platform key
• API URL: https://api.valyu.network (default)

3. Save credentials for reuse across workflows

Example Workflows

News Digest: Schedule trigger > Search operation > Answer operation > Email node

Content Monitoring: Weekly schedule > Extraction operation > Comparison logic > Slack notification

Research Pipeline: Webhook trigger > Deep Research operation > Google Sheets > Slack alert

Troubleshooting

• Restart n8n instance if node doesn't appear post-installation
• Verify API key has no extra spaces
• Allow extended timeouts (up to 30 minutes) for Heavy mode research
• Implement delays between operations if rate limiting occurs

Resources

• npm package: n8n-nodes-valyu
• GitHub: github.com/valyu-network/n8n-nodes-valyu
• Community support: discord.gg/umtmSsppRY

OpenAI Integration

Integrate Valyu's deep search capabilities directly into your OpenAI applications using the provider system with OpenAI's Responses API. This enables your AI agents to access real-time information from academic papers, news, financial data, and authoritative sources.

Installation

pip install valyu openai

Set your API keys:

export VALYU_API_KEY="your-valyu-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Basic Usage

The OpenAI provider handles the integration with the Responses API:

from openai import OpenAI
from valyu import OpenAIProvider
from dotenv import load_dotenv

load_dotenv()

# Initialize clients
openai_client = OpenAI()
provider = OpenAIProvider()

# Get Valyu tools
tools = provider.get_tools()

# Create a research request
messages = [
    {
        "role": "user",
        "content": "What are the latest developments in quantum computing? Write a summary of your findings."
    }
]

# Step 1: Call OpenAI Responses API with tools
response = openai_client.responses.create(
    model="gpt-5",
    input=messages,
    tools=tools,
)

# Step 2: Execute tool calls
tool_results = provider.execute_tool_calls(response)

# Step 3: Get final response with search results
if tool_results:
    updated_messages = provider.build_conversation(messages, response, tool_results)
    final_response = openai_client.responses.create(
        model="gpt-5",
        input=updated_messages,
        tools=tools,
    )
    print(final_response.output_text)
else:
    print(response.output_text)

Important: This uses OpenAI's Responses API (responses.create()), not Chat Completions!

How It Works

The OpenAIProvider handles everything:

1. Tool Registration: Automatically formats Valyu search for OpenAI Responses API 2. Tool Execution: Manages search API calls behind the scenes 3. Conversation Flow: Builds proper message sequences with tool results

Research Agent Example

from openai import OpenAI
from valyu import OpenAIProvider

def create_research_agent():
    client = OpenAI()
    provider = OpenAIProvider()
    tools = provider.get_tools()

    def research(query: str) -> str:
        messages = [
            {
                "role": "system",
                "content": "You are a research assistant with access to real-time information. Always cite your sources."
            },
            {
                "role": "user",
                "content": query
            }
        ]

        response = client.responses.create(
            model="gpt-5",
            input=messages,
            tools=tools,
        )

        tool_results = provider.execute_tool_calls(response)

        if tool_results:
            updated_messages = provider.build_conversation(messages, response, tool_results)
            final_response = client.responses.create(
                model="gpt-5",
                input=updated_messages,
                tools=tools,
            )
            return final_response.output_text

        return response.output_text

    return research

# Usage
agent = create_research_agent()
result = agent("Find the price of Bitcoin and Nvidia over the last 2 years")
print(result)

Financial Analysis Example

def create_financial_agent():
    client = OpenAI()
    provider = OpenAIProvider()
    tools = provider.get_tools()

    def analyze_market(assets: list) -> str:
        query = f"Get the latest news and price data for {', '.join(assets)}, then provide a detailed market analysis report"

        messages = [
            {
                "role": "system",
                "content": "You are a financial analyst. Provide data-driven insights with specific numbers and sources."
            },
            {
                "role": "user",
                "content": query
            }
        ]

        response = client.responses.create(
            model="gpt-5",
            input=messages,
            tools=tools,
        )

        tool_results = provider.execute_tool_calls(response)

        if tool_results:
            updated_messages = provider.build_conversation(messages, response, tool_results)
            final_response = client.responses.create(
                model="gpt-5",
                input=updated_messages,
                tools=tools,
            )
            return final_response.output_text

        return response.output_text

    return analyze_market

# Usage
financial_agent = create_financial_agent()
analysis = financial_agent(["Bitcoin", "Ethereum", "Tesla"])
print(analysis)

Model Selection

response = client.responses.create(
    model="gpt-5-mini",  # Faster, cheaper
    # model="gpt-5",      # More capable
    # model="o1-preview", # Advanced reasoning
    input=messages,
    tools=tools,
)

Search Parameters

The AI model can automatically use advanced search parameters based on your query context:

• max_num_results: Limit results (1-20, up to 100 with special API key)
• included_sources: Search specific domains or datasets
• excluded_sources: Exclude certain sources
• category: Guide search to specific topics
• start_date/end_date: Time-bounded searches
• relevance_threshold: Filter by relevance (0-1)

Best Practices

Use Clear System Prompts

messages = [
    {
        "role": "system",
        "content": """You are a research assistant with access to real-time information.

        Guidelines:
        - Always cite sources from search results
        - Provide specific data points and numbers
        - If information is recent, mention the date
        - Do not use search operators (site:, OR, AND, quotes). Use natural keyword queries.
        """
    },
    {
        "role": "user",
        "content": user_query
    }
]

Multi-Turn Conversations

class ResearchChat:
    def __init__(self):
        self.client = OpenAI()
        self.provider = OpenAIProvider()
        self.tools = self.provider.get_tools()
        self.messages = []

    def add_system_message(self, content: str):
        self.messages.append({"role": "system", "content": content})

    def chat(self, user_message: str) -> str:
        self.messages.append({"role": "user", "content": user_message})

        response = self.client.responses.create(
            model="gpt-5",
            input=self.messages,
            tools=self.tools,
        )

        tool_results = self.provider.execute_tool_calls(response)

        if tool_results:
            self.messages = self.provider.build_conversation(
                self.messages, response, tool_results
            )
            final_response = self.client.responses.create(
                model="gpt-5",
                input=self.messages,
                tools=self.tools,
            )
            assistant_message = final_response.output_text
        else:
            assistant_message = response.output_text

        self.messages.append({"role": "assistant", "content": assistant_message})
        return assistant_message

# Usage
chat = ResearchChat()
chat.add_system_message("You are a helpful research assistant.")
response = chat.chat("What's the latest news about renewable energy?")

API Reference

OpenAIProvider

class OpenAIProvider:
    def __init__(self, valyu_api_key: Optional[str] = None):
        """Initialize provider. API key auto-detected from environment if not provided."""

    def get_tools(self) -> List[Dict]:
        """Get list of tools formatted for OpenAI Responses API."""

    def execute_tool_calls(self, response) -> List[Dict]:
        """Execute tool calls from OpenAI Responses API response."""

    def build_conversation(self, input_messages, response, tool_results) -> List[Dict]:
        """Build updated message list with tool results."""

Resources

• OpenAI Responses API - Official documentation
• Valyu API Reference - Complete API documentation
• Python SDK - Full SDK documentation
• Get API Key - Sign up for free $10 credit

Vercel AI SDK Integration

AI SDK tools for Valyu search API, built for Vercel AI SDK v5.

Installation

npm install @valyu/ai-sdk

Get your free API key from Valyu Platform - $10 in free credits when you sign up!

Add to your .env file:

VALYU_API_KEY=your-api-key-here

Quick Start

import { generateText } from "ai";
import { webSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Latest data center projects for AI inference workloads?',
  tools: {
    webSearch: webSearch(),
  },
});

console.log(text);

Available Search Tools

• webSearch - News, current events, general web content
• financeSearch - Stock prices, earnings, insider transactions, dividends, balance sheets
• paperSearch - Full-text search of PubMed, arXiv, bioRxiv, medRxiv
• bioSearch - Clinical trials, FDA drug labels, ChEMBL, DrugBank, Open Targets
• patentSearch - USPTO full-text patent search
• secSearch - SEC filings (10-K, 10-Q, 8-K)
• economicsSearch - Economic indicators from BLS, FRED, World Bank
• companyResearch - Comprehensive company intelligence reports

Search Tool Examples

Finance Search

import { generateText, stepCountIs } from "ai";
import { financeSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What was the stock price of Apple from the beginning of 2020 to 14th feb?',
  tools: {
    financeSearch: financeSearch(),
  },
  stopWhen: stepCountIs(10),
});

Paper Search

import { generateText, stepCountIs } from "ai";
import { paperSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Psilocybin effects on cellular lifespan and longevity in mice?',
  tools: {
    paperSearch: paperSearch(),
  },
  stopWhen: stepCountIs(10),
});

Datasources Discovery Tools

datasources

List available data sources with metadata, schemas, and pricing.

import { generateText } from "ai";
import { datasources } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What data sources are available for financial research?',
  tools: {
    datasources: datasources(),
  },
});

datasourcesCategories

List all available categories with dataset counts.

import { generateText } from "ai";
import { datasourcesCategories } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What categories of data are available?',
  tools: {
    datasourcesCategories: datasourcesCategories(),
  },
});

Multi-Tool Search

import { generateText, stepCountIs } from "ai";
import { paperSearch, bioSearch, financeSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Research the commercialization of CRISPR technology',
  tools: {
    papers: paperSearch({ maxNumResults: 3 }),
    medical: bioSearch({ maxNumResults: 3 }),
    finance: financeSearch({ maxNumResults: 3 }),
  },
  stopWhen: stepCountIs(3),
});

Configuration Options

webSearch({
  apiKey: "your-api-key",
  searchType: "proprietary",
  maxNumResults: 10,
  relevanceThreshold: 0.8,
  maxPrice: 0.01,
  category: "technology",
  includedSources: ["arxiv", "pubmed"],
  isToolCall: true,
})

Streaming Results

import { streamText, stepCountIs } from "ai";
import { paperSearch } from "@valyu/ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";

const result = streamText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  prompt: 'Summarize recent quantum computing research',
  tools: {
    papers: paperSearch(),
  },
  stopWhen: stepCountIs(3),
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Best Practices

System Prompting

const result = await generateText({
  model: openai('gpt-5'),
  messages: [
    {
      role: 'system',
      content: `You are an AI research assistant with access to specialized search tools.
      - Use webSearch for current events and general web content
      - Use paperSearch for academic research and scientific papers
      - Use financeSearch for stock prices, earnings, and market data
      - Use bioSearch for medical research, clinical trials, drug data
      - Always cite sources using Markdown links: [Title](URL)`
    },
  ],
  tools: {
    web: webSearch(),
    papers: paperSearch(),
    finance: financeSearch(),
    bio: bioSearch(),
  },
  stopWhen: stepCountIs(3),
});

Cost Control

webSearch({
  maxPrice: 0.01,
  maxNumResults: 5,
  relevanceThreshold: 0.8,
})

Resources

• Valyu Platform - Get your API keys
• Valyu Documentation - Full API documentation
• GitHub Repository - View source code

Valyu Search Prompting Guide

Best practices for writing effective queries that return high-quality, relevant results.

Core Principle

Better queries = better results. Precise queries yield more relevant information, reducing noise and improving AI response quality.

Query Anatomy

Effective searches combine four elements:

Query Length

Keep queries under 400 characters. Use focused phrasing, not lengthy explanations.

# Too long
"I'm looking for information about the latest developments in artificial
intelligence, specifically focusing on large language models and their
applications in healthcare settings, preferably from recent peer-reviewed
academic papers published in 2024"

# Better
"large language models healthcare applications 2024 peer-reviewed"

Split Complex Requests

Break multifaceted research into separate, targeted queries.

# Don't do this
"everything about Tesla including stock performance, new products,
and Elon Musk tweets"

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

Avoid Search Operators

Valyu uses semantic search. Don't use traditional operators:

# Don't use
site:arxiv.org transformer attention
"exact phrase match"
machine learning OR deep learning

# Instead use
transformer attention mechanism arxiv
transformer attention mechanism research
machine learning deep learning applications

Use included_sources parameter instead of site: operators.

Domain-Specific Queries

Academic/Research

# Good: Specific terminology + constraints
"CRISPR gene editing off-target effects 2024"
"attention mechanism transformer architecture survey"
"GLP-1 receptor agonists weight loss clinical trials"

# Bad: Vague
"gene editing research"
"AI papers"
"diabetes medication studies"

Financial

# Good: Specific metrics + timeframe
"Apple revenue growth Q4 2024 earnings"
"NVIDIA GPU market share datacenter 2024"
"Federal Reserve interest rate decision December 2024"

# Bad: Too broad
"Apple financial information"
"tech stocks"
"interest rates"

News/Current Events

# Good: Specific event + recency
"OpenAI GPT-5 announcement 2024"
"EU AI Act implementation timeline"
"SpaceX Starship test flight results"

# Bad: Generic
"AI news"
"space news"
"tech regulations"

Parameter Combinations

Combine good queries with API parameters:

{
  query: "mRNA vaccine cancer immunotherapy clinical trials",
  search_type: "proprietary",
  included_sources: ["pubmed", "biorxiv"],
  start_date: "2024-01-01",
  relevance_threshold: 0.7,
  max_num_results: 15
}

Common Mistakes

Query Templates by Use Case

Market Research

"{company} {metric} {timeframe} {source_type}"
→ "Tesla revenue growth Q4 2024 SEC filing"

Academic Literature

"{topic} {methodology} {finding_type} {year}"
→ "transformer architecture attention mechanism survey 2024"

Competitive Analysis

"{company} vs {competitor} {aspect} {year}"
→ "OpenAI vs Anthropic API pricing comparison 2024"

Technical Documentation

"{technology} {specific_feature} {use_case}"
→ "React Server Components data fetching patterns"

News Monitoring

"{entity} {event_type} {timeframe}"
→ "Federal Reserve policy announcement December 2024"

Iterative Refinement

Start broad, then narrow based on results:

Round 1: "AI chip market 2024"
→ Too many results, mixed relevance

Round 2: "AI inference chip market share datacenter 2024"
→ Better focus, still broad

Round 3: "NVIDIA H100 vs AMD MI300 inference performance benchmark"
→ Specific, actionable results

Source Filtering Best Practices

Use included_sources for domain authority:

// Academic research
included_sources: ["arxiv", "pubmed", "nature", "science"]

// Financial analysis
included_sources: ["sec.gov", "bloomberg", "reuters", "wsj"]

// Tech news
included_sources: ["techcrunch", "theverge", "arstechnica"]

// Official documentation
included_sources: ["docs.python.org", "react.dev", "developer.mozilla.org"]

Relevance Threshold Tuning

Summary

1. Be specific - Use domain terminology 2. Be concise - Under 400 characters 3. Be focused - One topic per query 4. Use parameters - Combine query + filters 5. Iterate - Refine based on results

Academic Search

Search peer-reviewed papers across multiple scholarly databases.

Available Datasets

• valyu/valyu-arxiv - Preprints across all research fields
• valyu/valyu-pubmed - Medical and life sciences
• wiley/wiley-finance-papers - Finance and economics
• valyu/valyu-biorxiv - Life sciences preprints
• valyu/valyu-medrxiv - Clinical and health research preprints

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

// Search specific academic sources
const response = await valyu.search({
  query: "CRISPR gene editing therapeutic applications",
  searchType: "proprietary",
  includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
  maxNumResults: 20,
  startDate: "2024-01-01",
});

// Cross-disciplinary research
const crossDisciplinary = await valyu.search({
  query: "transformer architecture neural networks",
  searchType: "proprietary",
  includedSources: [
    "valyu/valyu-arxiv",
    "nature.com",
    "science.org"
  ],
  maxNumResults: 15,
});

from valyu import Valyu

valyu = Valyu()

# Search specific academic sources
response = valyu.search(
    query="CRISPR gene editing therapeutic applications",
    search_type="proprietary",
    included_sources=["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
    max_num_results=20,
    start_date="2024-01-01",
)

# Cross-disciplinary research
cross_disciplinary = valyu.search(
    query="transformer architecture neural networks",
    search_type="proprietary",
    included_sources=[
        "valyu/valyu-arxiv",
        "nature.com",
        "science.org"
    ],
    max_num_results=15,
)

CLI

scripts/valyu search paper "CRISPR gene editing therapeutic applications" 20

Search All Data Sources

Search across web content, academic journals, financial data, and proprietary datasets. By setting the searchType to all, it searches over everything all at once.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const response = await valyu.search({
  query: "latest developments in quantum computing",
  searchType: "all",
});

response.results.forEach(result => {
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.url}`);
  console.log(`Source: ${result.sourceType}`);
  console.log(`Content: ${result.content.substring(0, 200)}...`);
});

from valyu import Valyu

valyu = Valyu(YOUR_VALYU_API_KEY_HERE)

response = valyu.search(
    query="latest developments in quantum computing",
    max_num_results=5,
    search_type="all",
)

for result in response["results"]:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Source: {result['source_type']}")
    print(f"Content: {result['content'][:200]}...")

CLI

scripts/valyu search web "latest developments in quantum computing" 10

Search Proprietary Data

Valyu has many proprietary data sources. Set the searchType parameter to proprietary.

import { Valyu } from "valyu-js";

const valyu = new Valyu(YOUR_VALYU_API_KEY_HERE);

const response = await valyu.search({
  query: "latest developments in quantum computing",
  searchType: "proprietary",
});

response.results.forEach(result => {
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.url}`);
  console.log(`Source: ${result.sourceType}`);
  console.log(`Content: ${result.content.substring(0, 200)}...`);
});

from valyu import Valyu

valyu = Valyu(YOUR_VALYU_API_KEY_HERE)

response = valyu.search(
    query="latest developments in quantum computing",
    max_num_results=5,
    search_type="proprietary",
)

for result in response["results"]:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Source: {result['source_type']}")
    print(f"Content: {result['content'][:200]}...")

CLI

scripts/valyu search paper "latest developments in quantum computing" 10