Skip to main content
POST
/
v1
/
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>"

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

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]