curl --request POST \
  --url https://api.valyu.ai/v1/answer \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "What are the latest FDA-approved treatments for type 2 diabetes?"
}
'

"<string>"

{
  "success": false,
  "error": "Invalid search_type. Must be 'all', 'web', 'proprietary', or 'news'"
}

{
  "success": false,
  "error": "Invalid API key"
}

{
  "success": false,
  "error": "Insufficient credits. Please top up your account at platform.valyu.ai"
}

{
  "success": false,
  "error": "API key does not have inference permission"
}

{
  "success": false,
  "error": "Rate limit exceeded. Please retry after the Retry-After period."
}

{
  "success": false,
  "error": "Internal server error. Please try again later."
}

Answer

Get AI-powered answers with real-time search

Searches across web, academic, and financial sources, then uses AI to generate a readable, cited response. Returns results as a Server-Sent Events (SSE) stream.

The AI agent performs multi-round search with up to 2 tool call rounds (3 in fast_mode), can decompose queries into sub-queries, and synthesizes findings into a coherent answer.

SSE Event Types

Events are sent as data: {json}\n\n with the following types:

Event	Description
`search_results`	Search sources found (may occur multiple times)
`content`	Partial answer text chunk (OpenAI-compatible delta format)
`metadata`	Final metadata with costs, token usage, and all search results
`[DONE]`	Stream complete

Cost Structure

Each request costs a base of ~$0.10 plus variable search and AI token costs. The cost object in the metadata event provides a full breakdown.

POST

answer

curl --request POST \
  --url https://api.valyu.ai/v1/answer \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "What are the latest FDA-approved treatments for type 2 diabetes?"
}
'

"<string>"

{
  "success": false,
  "error": "Invalid search_type. Must be 'all', 'web', 'proprietary', or 'news'"
}

{
  "success": false,
  "error": "Invalid API key"
}

{
  "success": false,
  "error": "Insufficient credits. Please top up your account at platform.valyu.ai"
}

{
  "success": false,
  "error": "API key does not have inference permission"
}

{
  "success": false,
  "error": "Rate limit exceeded. Please retry after the Retry-After period."
}

{
  "success": false,
  "error": "Internal server error. Please try again later."
}

Authorizations

X-API-Key

string

header

required

API key for authentication. Get yours at platform.valyu.ai.

Body

application/json

Answer API request parameters.

query

string

required

The question or research query to answer.

Example:

"What are the latest FDA-approved treatments for type 2 diabetes?"

search_type

enum<string>

default:all

Controls which data sources are searched.

all - Web and proprietary sources (default)
web - Web search only
proprietary - Academic, financial, and premium sources only
news - News articles only

Available options:

all,

web,

proprietary,

news

included_sources

string[]

Sources to include. Accepts domains, URLs, dataset identifiers, or presets ("finance", "medical").

Example:

["pubmed.ncbi.nlm.nih.gov"]

excluded_sources

string[]

Sources to exclude. Same format as included_sources except presets are not supported.

data_max_price

number

default:1

Maximum budget in USD for the search data component. Converted to CPM internally.

Required range: x > 0

Example:

1

start_date

string<date>

Filter results published on or after this date. Format: YYYY-MM-DD.

Example:

"2024-01-01"

end_date

string<date>

Filter results published on or before this date. Format: YYYY-MM-DD.

Example:

"2024-12-31"

country_code

enum<string>

ISO 3166-1 alpha-2 country code for geo-targeted search.

Available options:

ALL,

AR,

AU,

AT,

BE,

BR,

CA,

CL,

DK,

FI,

FR,

DE,

HK,

IN,

ID,

IT,

JP,

KR,

MY,

MX,

NL,

NZ,

NO,

CN,

PL,

PT,

PH,

RU,

SA,

ZA,

ES,

SE,

CH,

TW,

TR,

GB,

US

fast_mode

boolean

default:false

Enable fast mode for lower latency. Uses 3 tool call rounds instead of 2 and higher result counts per query.

structured_output

object | null

JSON Schema defining the desired output structure. When set, the AI returns a JSON object matching this schema instead of free-form text. Max depth 10, max 50 properties, max 5000 characters.

Example:

{
  "type": "object",
  "properties": {
    "treatments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "approval_date": { "type": "string" },
          "mechanism": { "type": "string" }
        }
      }
    }
  }
}

system_instructions

string | null

Custom system instructions for the AI. Replaces the default research agent prompt. Max 2000 characters.

Maximum string length: 2000

Example:

"You are a medical research assistant. Cite all sources."

Response

SSE stream of search results, answer chunks, and metadata.

Server-Sent Events stream. Each event has format: data: {json}\n\n

search_results event:

{"search_results": [{"title": "...", "url": "...", "content": "...", ...}]}

content event (OpenAI-compatible):

{"choices": [{"delta": {"role": "assistant", "content": "text chunk"}, "index": 0}]}

metadata event:

{"success": true, "tx_id": "ai_tx_...", "data_type": "unstructured", "search_results": [...], "search_metadata": {"tx_ids": [...], "number_of_results": 10, "total_characters": 50000}, "ai_usage": {"input_tokens": 15000, "output_tokens": 2000}, "cost": {"total_deduction_dollars": 0.15, "search_deduction_dollars": 0.03, "ai_deduction_dollars": 0.10, "contents_deduction_dollars": 0.02}}

done signal:

data: [DONE]

Poll async content extraction job status Create a DeepResearch task

Overview

Search Tools

DeepResearch

DeepResearch (Batch)

Workflows

Datasources

Search

Contents

Answer

DeepResearch

Batches

Datasources

Workflows

Get AI-powered answers with real-time search

SSE Event Types

Cost Structure

Authorizations

Body

Response