POST
/
answer
curl --request POST \
  --url https://api.valyu.network/answer \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "query": "latest developments in quantum computing",
  "data_max_price": 30
}'
{
  "success": true,
  "ai_tx_id": "ai_tx_12345-abcd-efgh",
  "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 advances in quantum error correction, new quantum algorithms for optimization problems, and progress in quantum hardware scalability.",
  "data_type": "unstructured",
  "search_results": [
    {
      "title": "Quantum Computing Breakthrough 2024",
      "url": "https://example.com/quantum-news",
      "snippet": "Scientists achieve new milestone...",
      "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
  }
}

Authorizations

​
x-api-key
string
header
required

Your Valyu API key. Get one at platform.valyu.network

Body

application/json
​
query
string
required

The search query

Example:

"latest developments in quantum computing"

​
system_instructions
string | null

Custom instructions for AI processing

Maximum length: 2000
Example:

"Focus on practical applications and commercial impact"

​
structured_output
object | null

JSON schema for structured output. When provided, enables JSON mode and returns structured data

​
search_type
enum<string>
default:all

Type of search to perform

Available options:
all,
web,
proprietary
Example:

"all"

​
fast_mode
boolean
default:false

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

Example:

true

​
data_max_price
number
default:30

Maximum price in dollars for a thousand retrievals (CPM) for search data only (does not affect AI costs)

Required range: x >= 0
Example:

30

​
included_sources
string[]

List of specific sources to search (URLs, domains or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.network/blog' or 'valyu.network/blog'), only that specific path will be searched. For entire domains, use either the domain name (e.g., 'valyu.network') or the base URL (e.g., 'https://valyu.network').

Example:
[
  "https://docs.aws.amazon.com/",
  "techcrunch.com/news",
  "valyu/valyu-arxiv"
]
​
excluded_sources
string[]

List of specific sources to exclude from search (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.network/blog' or 'valyu.network/blog'), only that specific path will be excluded. For entire domains, use either the domain name (e.g., 'valyu.network') or the base URL (e.g., 'https://valyu.network').

Example:
[
  "https://news.ycombinator.com/",
  "github.com/valyu",
  "valyu/valyu-pubmed"
]
​
start_date
string<date> | null

Start date filter (YYYY-MM-DD)

Example:

"2024-01-01"

​
end_date
string<date> | null

End date filter (YYYY-MM-DD)

Example:

"2024-12-31"

​
country_code
string | null

2-letter ISO country code to bias search results to a specific country

Example:

"US"

Response

Successful AI processing

​
success
boolean
required

Whether the request was successful

Example:

true

​
ai_tx_id
string
required

AI transaction ID

Example:

"ai_tx_12345-abcd-efgh"

​
original_query
string
required

The original search query

Example:

"latest developments in quantum computing"

​
contents
required

AI-processed response content AI-generated text response (when data_type is unstructured)

Example:

"Based on the latest research findings, quantum computing has made significant breakthroughs in 2024..."

​
data_type
enum<string>
required

Type of response data

Available options:
unstructured,
structured
Example:

"unstructured"

​
search_results
object[]
required

Simplified search results used for AI processing

​
search_metadata
object
required

Search transaction metadata

​
ai_usage
object
required

AI token usage information

​
cost
object
required

Cost breakdown information