Answer Endpoint Guide

The Answer API searches across web, academic, and financial sources, then uses AI to generate a readable response with citations. You get a finished answer instead of raw search results.

Ask a question

from valyu import Valyu

valyu = Valyu()  # reads VALYU_API_KEY from env

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

import { Valyu } from "valyu-js";

const valyu = new Valyu(); // reads VALYU_API_KEY from env

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

curl -X POST https://api.valyu.ai/v1/answer \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "query": "latest developments in quantum computing" }'

Common options

Option	What it does
`search_type`	`all` (default), `web`, `proprietary`, or `news`
`system_instructions`	Tell the AI how to process and format the answer
`structured_output`	A JSON schema for a consistent, parseable response
`included_sources`	Restrict to datasets, domains, or paths
`start_date` / `end_date`	Limit results to a date range (`YYYY-MM-DD`)
`country_code`	Bias results toward a region (e.g. `"US"`)
`fast_mode`	Lower latency, finance and web sources prioritised
`data_max_price`	Cap search data cost (USD, default $1.0)

data = valyu.answer(
    query="climate change research",
    system_instructions="Focus on commercial impact. Summarise key findings as bullet points.",
    included_sources=["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
    start_date="2024-01-01",
    data_max_price=2.0,  # cap search data cost at $2.00 (default is $1.0)
)
print(data.contents)

Search and AI are billed separately - the cost field breaks down both. Use data_max_price to cap search cost and fast_mode for lower latency.

Streaming

Enable streaming to receive the answer progressively. The stream sends search results first, then content chunks, then metadata.

for chunk in valyu.answer("What is machine learning?", streaming=True):
    if chunk.type == "search_results":
        print(f"Found {len(chunk.search_results)} sources")
    elif chunk.type == "content" and chunk.content:
        print(chunk.content, end="", flush=True)
    elif chunk.type == "metadata":
        print(f"\nCost: ${chunk.cost.total_deduction_dollars:.4f}")
    elif chunk.type == "error":
        print(f"Error: {chunk.error}")

const stream = await valyu.answer("What is machine learning?", { streaming: true });

for await (const chunk of stream) {
  if (chunk.type === "search_results") {
    console.log(`Found ${chunk.search_results?.length} sources`);
  } else if (chunk.type === "content" && chunk.content) {
    process.stdout.write(chunk.content);
  } else if (chunk.type === "metadata") {
    console.log(`\nCost: $${chunk.cost?.total_deduction_dollars.toFixed(4)}`);
  } else if (chunk.type === "error") {
    console.error(`Error: ${chunk.error}`);
  }
}

curl -X POST https://api.valyu.ai/v1/answer \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "query": "What is machine learning?", "streaming": true }'

Chunk types: search_results (sources, streamed first), content (partial answer text), metadata (final costs, tokens, full results), done, error.

Structured output

Pass a JSON schema in structured_output to get a parseable object back instead of prose:

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"},
                    },
                    "required": ["name", "revenue"],
                },
            },
            "market_summary": {"type": "string"},
        },
        "required": ["companies", "market_summary"],
    },
)
print(data.contents)  # contents is a structured object matching your schema

Keep schemas shallow, mark essential fields required, add description fields to guide the AI, and use maxItems to bound arrays.

Response format

{
  "success": true,
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "original_query": "latest developments in quantum computing",
  "contents": "Based on the latest research, quantum computing made significant progress in 2024...",
  "search_results": [
    {
      "title": "IBM Unveils 1000-Qubit Quantum Processor",
      "url": "https://example.com/ibm-quantum",
      "snippet": "IBM announced a breakthrough in quantum computing...",
      "source": "web",
      "date": "2024-03-15"
    }
  ],
  "search_metadata": { "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
  }
}

Without structured_output, contents is a string. When you pass a structured_output schema, contents is instead a structured object matching that schema - in Python, check with isinstance(response.contents, dict).

Response fields

Field	Description
`contents`	The AI-generated answer (string, or a structured object when `structured_output` is set)
`search_results`	Search results the AI used
`search_metadata`	Search transaction details
`ai_usage`	Token counts
`cost`	Cost breakdown (search + AI)

Next steps

API reference

Complete parameter documentation

Python SDK

Python integration

TypeScript SDK

TypeScript integration

Integrations

LangChain, LlamaIndex, and more

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Compare

Account & Pricing

Other

Answer API

Ask a question

Common options

Streaming

Structured output

Response format

Next steps

API reference

Python SDK

TypeScript SDK

Integrations

​Ask a question

​Common options

​Streaming

​Structured output

​Response format

​Next steps

API reference

Python SDK

TypeScript SDK

Integrations

Ask a question

Common options

Streaming

Structured output

Response format

Next steps