Answer Endpoint Guide

Get AI-powered answers that combine real-time search with advanced reasoning. The Answer API searches across web, academic, and financial data sources, then processes the results with AI to deliver readable, contextual responses.

Why Use the Answer API

The Answer API provides responses powered by real-time search that enable:

🤖 LLM-Native Responses - Get AI-generated answers instead of raw search results
🔍 Real-Time Knowledge - Access up-to-date information from web and proprietary sources
📊 Structured Outputs - Define JSON schemas for consistent, parseable responses
🎯 Source Control - Include or exclude specific domains and datasets

Key Answer API Features

AI-Enhanced Search

Intelligent Processing Combine search results with AI reasoning for comprehensive answers.

Fast Mode

Optimized Speed Reduced latency with Finance + Web sources prioritization while maintaining AI quality.

Structured Responses

JSON Schema Support Define structured output formats for consistent, parseable responses.

Source Filtering

Granular Control Include or exclude specific domains, URLs, and datasets from search.

Date Filtering

Date Filtering Filter search results by date range.

Getting Started

Basic AI-Powered Query

Ask any question and get an intelligent response powered by real-time search:

from valyu import Valyu

valyu = Valyu() # Uses VALYU_API_KEY from env

data = valyu.answer(
query="latest developments in quantum computing",
)
print(data["contents"]) # AI-processed response

Fast Mode for Faster Responses

Enable fast mode for reduced latency but shorter results. Best for general purpose queries:

from valyu import Valyu

valyu = Valyu()

# Fast mode for reduced response time

data = valyu.answer(
query="current market trends in tech stocks",
fast_mode=True, # Enable fast mode
data_max_price=30.0
)
print(data["contents"])

This returns an AI-processed response based on the most relevant search results.

Search Type Options

Control which data sources to search:

Type	Description	Best For
`all`	Search web and proprietary sources (default)	Comprehensive coverage
`web`	Web search only	Current events, general topics
`proprietary`	Academic, financial, and premium sources only	Research, technical analysis

Custom AI Instructions

Guide the AI processing with custom system instructions:

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"])

Advanced Features

Source Filtering

Control exactly which sources to include or exclude:

from valyu import Valyu

valyu = Valyu()

data = valyu.answer(
query="artificial intelligence research trends",
included_sources=[
"valyu/valyu-arxiv",
"nature.com",
"valyu/valyu-pubmed",
]
)
print(data["contents"])

Source Filtering Rules:

Domains: Use "example.com" to include/exclude entire domains
Specific Paths: Use "https://example.com/blog" for specific sections
Datasets: Use dataset names like "valyu/valyu-arxiv" for proprietary sources

Structured Output with JSON Schema

Get responses in a consistent, structured format:

from valyu import Valyu

valyu = Valyu()

data = valyu.answer(
query="top tech companies financial performance 2024",
structured_output={
"type": "object",
"properties": {
"companies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"revenue": {"type": "string"},
"growth_rate": {"type": "string"},
"key_metrics": {"type": "array", "items": {"type": "string"}},
},
"required": ["name", "revenue"],
},
},
"market_summary": {"type": "string"},
"analysis_date": {"type": "string"},
},
"required": ["companies", "market_summary"],
},
)
print(data["contents"])

Date Range Filtering

Focus on specific time periods:

from valyu import Valyu

valyu = Valyu()

data = valyu.answer(
query="cryptocurrency market analysis",
start_date="2024-01-01",
end_date="2024-12-31",
country_code="US",
)
print(data["contents"])

Response Format

Unstructured Response (Default)

{
  "success": true,
  "ai_tx_id": "ai_tx_12345678-1234-1234-1234-123456789abc",
  "data_type": "unstructured",
  "original_query": "latest developments in quantum computing",
  "contents": "Based on the latest research findings, quantum computing has made significant breakthroughs in 2024. Key developments include:\n\n**Hardware Advances**: IBM's new 1000-qubit processor demonstrates improved error correction rates, while Google's quantum supremacy claims continue to be validated through practical applications...\n\n**Commercial Applications**: Financial institutions are beginning to deploy quantum algorithms for risk analysis and portfolio optimisation, with early results showing 15-20% improvements in processing speed...",
  "search_results": [
    {
      "title": "IBM Unveils 1000-Qubit Quantum Processor",
      "url": "https://example.com/ibm-quantum",
      "snippet": "IBM announced breakthrough in quantum computing...",
      "source": "web",
      "date": "2024-03-15",
      "length": 2500
    }
  ],
  "search_metadata": {
    "tx_ids": ["search_tx_67890"],
    "number_of_results": 8,
    "total_characters": 45000
  },
  "ai_usage": {
    "input_tokens": 1250,
    "output_tokens": 420
  },
  "cost": {
    "total_deduction_dollars": 0.027,
    "search_deduction_dollars": 0.015,
    "ai_deduction_dollars": 0.012
  }
}

Structured Response (JSON Schema)

{
  "success": true,
  "ai_tx_id": "ai_tx_54321-dcba-hgfe",
  "data_type": "structured",
  "original_query": "top tech companies financial performance 2024",
  "contents": {
    "companies": [
      {
        "name": "Apple Inc.",
        "revenue": "$394.3 billion",
        "growth_rate": "+2.8%",
        "key_metrics": [
          "iPhone sales up 6%",
          "Services revenue $85.2B",
          "Record quarterly profit"
        ]
      },
      {
        "name": "Microsoft Corporation",
        "revenue": "$245.1 billion",
        "growth_rate": "+15.7%",
        "key_metrics": [
          "Azure growth 29%",
          "Office 365 users 400M",
          "AI integration boost"
        ]
      }
    ],
    "market_summary": "The tech sector showed resilience in 2024 with cloud computing and AI driving growth despite economic headwinds.",
    "analysis_date": "2024-12-01"
  },
  "search_results": [],
  "search_metadata": {
    "tx_ids": ["search_tx_98765"],
    "number_of_results": 6,
    "total_characters": 38000
  },
  "ai_usage": {
    "input_tokens": 1350,
    "output_tokens": 280
  },
  "cost": {
    "total_deduction_dollars": 0.033,
    "search_deduction_dollars": 0.018,
    "ai_deduction_dollars": 0.015
  }
}

Key Response Fields

Field	Description
`contents`	AI-generated response (string or structured object)
`data_type`	`"unstructured"` (text) or `"structured"` (JSON)
`search_results`	Simplified search results metadata used by AI
`search_metadata`	Cost breakdown and search transaction details
`ai_usage`	Token usage information
`cost`	Detailed cost breakdown

Common Use Cases

Research Assistant

Get comprehensive research summaries with citations:

{
  "query": "machine learning interpretability methods 2024",
  "system_instructions": "Provide a technical overview focusing on recent methodological advances. Include key papers and practical applications.",
  "search_type": "proprietary",
  "included_sources": ["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
  "data_max_price": 40.0
}

Market Analysis

Extract structured financial insights:

{
  "query": "renewable energy sector investment trends Q4 2024",
  "structured_output": {
    "type": "object",
    "properties": {
      "total_investment": { "type": "string" },
      "top_sectors": {
        "type": "array",
        "items": { "type": "string" }
      },
      "regional_breakdown": {
        "type": "object",
        "properties": {
          "north_america": { "type": "string" },
          "europe": { "type": "string" },
          "asia_pacific": { "type": "string" }
        }
      },
      "key_trends": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["total_investment", "key_trends"]
  },
  "search_type": "all",
  "data_max_price": 35.0
}

Technical Documentation Search

Find specific technical information with focused sources:

{
  "query": "Next.js app router best practices for large applications",
  "included_sources": [
    "https://nextjs.org/docs",
    "https://github.com/vercel/next.js",
    "vercel.com/blog"
  ],
  "system_instructions": "Focus on official recommendations and provide code examples where relevant.",
  "data_max_price": 20.0
}

News and Current Events

Get recent updates with time filtering:

{
  "query": "AI regulation developments European Union",
  "start_date": "2024-10-01",
  "end_date": "2024-12-31",
  "search_type": "web",
  "system_instructions": "Summarise recent policy changes and their potential impact on tech companies.",
  "data_max_price": 25.0
}

Best Practices

Optimise Your Queries

Be Specific: Use detailed queries for better search results
Set Appropriate Price Limits: Balance cost with data quality needs
Use Source Filtering: Focus on authoritative sources for your domain
Custom System Instructions: Guide AI processing for your specific use case

Structured Output Design

Keep Schemas Simple: Avoid overly complex nested structures
Use Required Fields: Mark essential fields as required
Provide Descriptions: Help AI understand expected content
Limit Array Sizes: Use maxItems to control response length

Cost Management

Monitor Both Costs: Track search data and AI processing costs separately
Adjust Price Limits: Use data_max_price to control search data costs
Optimise Sources: Exclude irrelevant sources to reduce data costs
Use Date Filters: Limit search scope to recent content when appropriate

Error Handling

from valyu import Valyu

valyu = Valyu()

try:
    data = valyu.answer(
        query="quantum computing applications",
    )
    if data.get("success"):
        print(data["contents"])  # AI-generated answer
    else:
        print(f"Processing failed: {data.get('error', 'Unknown error')}")
except Exception as e:
    print(f"Request failed: {e}")

Try the Answer API

Explore the complete API reference with interactive examples and detailed parameter documentation.

Next Steps

API Reference

Complete parameter documentation and examples

Python SDK

Easy integration with Python applications

TypeScript SDK

Type-safe integration for JavaScript/TypeScript

Integration Guides

Connect with LangChain, LlamaIndex, and more

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Account & Pricing

​Why Use the Answer API

​Key Answer API Features

AI-Enhanced Search

Fast Mode

Structured Responses

Source Filtering

Date Filtering

​Getting Started

​Basic AI-Powered Query

​Fast Mode for Faster Responses

​Search Type Options

​Custom AI Instructions

​Advanced Features

​Source Filtering

​Structured Output with JSON Schema

​Date Range Filtering

​Response Format

​Unstructured Response (Default)

​Structured Response (JSON Schema)

​Key Response Fields

​Common Use Cases

​Research Assistant

​Market Analysis

​Technical Documentation Search

​News and Current Events

​Best Practices

​Optimise Your Queries

​Structured Output Design

​Cost Management

​Error Handling

Try the Answer API

​Next Steps

API Reference

Python SDK

TypeScript SDK

Integration Guides

Why Use the Answer API

Key Answer API Features

Getting Started

Basic AI-Powered Query

Fast Mode for Faster Responses

Search Type Options

Custom AI Instructions

Advanced Features

Source Filtering

Structured Output with JSON Schema

Date Range Filtering

Response Format

Unstructured Response (Default)

Structured Response (JSON Schema)

Key Response Fields

Common Use Cases

Research Assistant

Market Analysis

Technical Documentation Search

News and Current Events

Best Practices

Optimise Your Queries

Structured Output Design

Cost Management

Error Handling

Next Steps