# Valyu Search

> Complete Valyu API toolkit with Search, Answer, Contents extraction, and DeepResearch. Use for web/academic/financial search, AI-powered answers, content extraction from URLs, and async deep research reports. Supports syntax like "Valyu(command, args)" for search, answer, contents, and deepresearch operations.

- Skill: `valyuai/valyu-search` (Agent Skill, multi-file: 48 files)
- Install (CLI): `npx skillmds@latest add valyuai/valyu-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/valyuai/valyu-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: valyuai (https://skillmd.com/u/valyuai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/valyuai/valyu-search

---


# Valyu Complete API Tool

## Reference Documentation

For detailed guidance, consult these references:

| Document | Purpose |
|----------|---------|
| [references/design-philosophy.md](references/design-philosophy.md) | Core principles and when to use Valyu |
| [references/datasources.md](references/datasources.md) | Available datasets and data coverage (40+ sources) |
| [references/api-guide.md](references/api-guide.md) | Complete API documentation for all endpoints |
| [references/prompting.md](references/prompting.md) | Best practices for writing effective search queries |
| [references/recipes.md](references/recipes.md) | Recipe index and common workflows |
| [references/search-recipes/](references/search-recipes/) | 14 search patterns (academic, finance, healthcare, news, monitoring) |
| [references/content-recipes/](references/content-recipes/) | 6 content extraction patterns (summarization, structured data) |
| [references/answer-recipes/](references/answer-recipes/) | 4 answer patterns (fast mode, streaming, structured output) |
| [references/deepresearch-recipes/](references/deepresearch-recipes/) | 3 research patterns (fast, lite, heavy modes) |
| [references/integrations/](references/integrations/) | SDK & platform integration guides (13 integrations) |

## Integrations

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

| Integration | File | Use Case |
|-------------|------|----------|
| **MCP Remote** | [integrations/mcp-server.md](references/integrations/mcp-server.md) | Claude Desktop, Claude Code CLI, OpenAI agents via MCP |
| **MCP Local** | [integrations/mcp-desktop.md](references/integrations/mcp-desktop.md) | Local MCP server with Python virtual environment |
| **Claude Code Plugin** | [integrations/claude-code-plugin.md](references/integrations/claude-code-plugin.md) | Direct plugin for Claude Code CLI |
| **LM Studio** | [integrations/lmstudio.md](references/integrations/lmstudio.md) | Enhance local LLMs with Valyu search |
| **AWS Bedrock** | [integrations/aws-agentcore.md](references/integrations/aws-agentcore.md) | Enterprise deployment with Strands Agents |
| **n8n** | [integrations/n8n.md](references/integrations/n8n.md) | Workflow automation integration |
| **Vercel AI SDK** | [integrations/vercel-ai-sdk.md](references/integrations/vercel-ai-sdk.md) | TypeScript tools for AI SDK v5 |
| **LangChain** | [integrations/langchain.md](references/integrations/langchain.md) | Python agents with ValyuSearchTool |
| **LlamaIndex** | [integrations/llamaindex.md](references/integrations/llamaindex.md) | ValyuToolSpec for RAG applications |
| **Claude Agent SDK** | [integrations/claude-agent-sdk.md](references/integrations/claude-agent-sdk.md) | Community SDK with MCP tools |
| **Anthropic** | [integrations/anthropic.md](references/integrations/anthropic.md) | AnthropicProvider for Claude API |
| **OpenAI** | [integrations/openai.md](references/integrations/openai.md) | OpenAIProvider for Responses API |
| **Google Gemini** | [integrations/google.md](references/integrations/google.md) | Gemini function calling integration |

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:
   ```bash
   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:
   ```bash
   $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:
   ```bash
   /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:**
   ```bash
   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)
```bash
scripts/valyu setup <api-key>
```

### 1. SEARCH - Multi-domain search
```bash
scripts/valyu search <type> <query> [maxResults]
```

### 2. ANSWER - AI-powered answers
```bash
scripts/valyu answer <query> [--fast] [--structured <schema>]
```

### 3. CONTENTS - Extract content from URLs
```bash
scripts/valyu contents <url> [--summary [instructions]] [--structured <schema>]
```

### 4. DEEPRESEARCH - Async research reports
```bash
scripts/valyu deepresearch create <query> [--model <fast|lite|heavy>] [--pdf]
scripts/valyu deepresearch status <task-id>
```

## 1. SEARCH API

### Search Types

| Type | Description | Sources |
|------|-------------|---------|
| `web` | General web search | All web sources |
| `finance` | Financial data | Stocks, SEC, earnings, crypto, forex |
| `paper` | Academic papers | arXiv, bioRxiv, medRxiv, PubMed |
| `bio` | Biomedical research | PubMed, clinical trials, drug labels |
| `patent` | Patent databases | Patent filings |
| `sec` | SEC filings | 10-K, 10-Q, 8-K reports |
| `economics` | Economic data | BLS, FRED, World Bank |
| `news` | News articles | News sources |

### Usage Examples

```bash
# 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

```json
{
  "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

```bash
# 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

```json
{
  "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

```bash
# 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

| Length | Characters | Use For |
|--------|-----------|---------|
| `short` | 25,000 | Summaries, key points |
| `medium` | 50,000 | Articles, blog posts (default) |
| `large` | 100,000 | Academic papers, long-form |
| `max` | Unlimited | Full document extraction |

### Output Format

```json
{
  "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

| Mode | Use Case | Typical Time |
|------|----------|--------------|
| `fast` | Quick lookups, simple questions | ~5 minutes |
| `lite` | Balanced research (default) | ~10-20 minutes |
| `heavy` | In-depth analysis, complex research | Up to ~90 minutes |

### Create Research Task

```bash
# 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

```bash
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

```json
{
  "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

```json
{
  "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

```bash
# 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:

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

Exit codes:
- `0` - Success
- `1` - Error (check JSON for details)

## Use Cases

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

### News Monitoring
```bash
# Latest news
scripts/valyu search news "AI regulation EU" 20
```

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

### Quick Q&A
```bash
# Fast answer
scripts/valyu answer "Who won the 2024 election?" --fast
```

### Academic Research
```bash
# Search papers
scripts/valyu search paper "CRISPR gene editing 2024" 15
```

### Financial Analysis
```bash
# 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.