> ## Documentation Index > Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Answer > Reference for the Valyu Answer endpoint that blends search results into AI-generated answers via POST /v1/answer. ## OpenAPI ````yaml POST /v1/answer openapi: 3.0.3 info: title: Valyu API version: 2.2.0 description: > The search API built for AI agents. One API that gives your AI unified access to web search, academic papers, financial data, SEC filings, clinical trials, patents, and 36+ proprietary data sources. ## Products | Product | Endpoint | Description | | --- | --- | --- | | **Search** | `POST /v1/search` | Multi-source search across web and proprietary datasets | | **Contents** | `POST /v1/contents` | Extract clean, structured content from URLs | | **Answer** | `POST /v1/answer` | AI-powered answers with real-time search | | **DeepResearch** | `POST /v1/deepresearch/tasks` | Async research agents for comprehensive analysis | | **Datasources** | `GET /v1/datasources` | Discover available data sources and their schemas | ## Authentication All endpoints require an API key passed via the `X-API-Key` header. Get your key at [platform.valyu.ai](https://platform.valyu.ai). ``` X-API-Key: your_api_key_here ``` ## Pricing Valyu uses transparent, pay-per-use pricing: - **Search**: CPM-based (cost per mille tokens retrieved) - **Contents**: $0.001 per URL extracted, +$0.001 with AI features - **Answer**: $0.10 per request + variable search and AI costs - **DeepResearch**: Fixed per-task pricing by mode ($0.10 - $15.00) See [docs.valyu.ai](https://docs.valyu.ai) for full pricing details. ## SDKs - [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu` - [TypeScript SDK](https://www.npmjs.com/package/valyu) - `npm install valyu` contact: name: Valyu Support url: https://valyu.ai email: support@valyu.ai x-logo: url: https://valyu.ai/logo.png altText: Valyu servers: - url: https://api.valyu.ai description: Production security: - ApiKeyAuth: [] tags: - name: Search description: >- Search across web, academic, financial, and proprietary data sources. Returns results ready for RAG pipelines, AI agents, and applications. externalDocs: description: Search API Guide url: https://docs.valyu.ai/search/quickstart - name: Contents description: >- Extract clean, structured content from web pages at scale. Supports batch processing, AI-powered summaries, structured extraction via JSON schemas, and async jobs for large URL sets. externalDocs: description: Contents API Guide url: https://docs.valyu.ai/guides/content-extraction - name: Answer description: >- Get AI-powered answers grounded in real-time search results. The Answer API searches across web, academic, and financial sources, then uses AI to generate a readable response via Server-Sent Events streaming. externalDocs: description: Answer API Guide url: https://docs.valyu.ai/guides/answer-api - name: DeepResearch description: >- Async research agents that perform comprehensive, multi-step research. DeepResearch searches multiple sources, analyzes content, and generates detailed reports with citations. Tasks run in the background and can take minutes to complete. externalDocs: description: DeepResearch Guide url: https://docs.valyu.ai/guides/deepresearch - name: Batches description: >- Run multiple DeepResearch tasks in parallel with shared configuration, unified monitoring, and aggregated cost tracking. externalDocs: description: Batch API Guide url: https://docs.valyu.ai/guides/deepresearch-batch-quickstart - name: Datasources description: >- Discover available data sources and their schemas. A tool manifest for AI agents - instead of hardcoding knowledge of available datasets, agents can query this API to discover sources, filter by category, and use `example_queries` for few-shot prompting. externalDocs: description: Datasources Guide url: https://docs.valyu.ai/guides/datasources externalDocs: description: Complete API Documentation url: https://docs.valyu.ai paths: /v1/answer: post: tags: - Answer summary: Get AI-powered answers with real-time search description: >- 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. operationId: answer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AnswerRequest' examples: basic: summary: Basic question value: query: >- What are the latest FDA-approved treatments for type 2 diabetes? structured: summary: Structured output with JSON schema value: query: >- Compare the top 5 electric vehicles by range and price in 2024 structured_output: type: object properties: vehicles: type: array items: type: object properties: name: type: string range_miles: type: number base_price: type: number filtered: summary: Source-filtered with custom instructions value: query: SEC enforcement actions against crypto exchanges search_type: proprietary included_sources: - finance system_instructions: >- You are a financial regulatory analyst. Focus on enforcement actions and penalties. start_date: '2024-01-01' responses: '200': description: SSE stream of search results, answer chunks, and metadata. content: text/event-stream: schema: type: string description: >- Server-Sent Events stream. Each event has format: `data: {json}\n\n` **search_results event:** ```json {"search_results": [{"title": "...", "url": "...", "content": "...", ...}]} ``` **content event (OpenAI-compatible):** ```json {"choices": [{"delta": {"role": "assistant", "content": "text chunk"}, "index": 0}]} ``` **metadata event:** ```json {"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] ``` '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' components: schemas: AnswerRequest: type: object required: - query additionalProperties: false description: Answer API request parameters. properties: query: type: string description: The question or research query to answer. example: What are the latest FDA-approved treatments for type 2 diabetes? search_type: type: string description: |- 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 enum: - all - web - proprietary - news default: all included_sources: type: array description: >- Sources to include. Accepts domains, URLs, dataset identifiers, or presets (`"finance"`, `"medical"`). items: type: string example: - pubmed.ncbi.nlm.nih.gov excluded_sources: type: array description: >- Sources to exclude. Same format as `included_sources` except presets are not supported. items: type: string source_biases: type: object description: >- Bias values for specific sources to influence ranking without hard filtering. Keys are domains or URL paths. Values are integers from -5 (strong demotion) to +5 (strong boost). additionalProperties: type: integer minimum: -5 maximum: 5 nullable: true example: nasa.gov: 5 noaa.gov: 3 nih.gov: 1 example.com: -4 data_max_price: type: number description: >- Maximum budget in USD for the search data component. Converted to CPM internally. default: 1 minimum: 0 exclusiveMinimum: true example: 1 start_date: type: string format: date description: >- Filter results published on or after this date. Format: `YYYY-MM-DD`. example: '2024-01-01' end_date: type: string format: date description: >- Filter results published on or before this date. Format: `YYYY-MM-DD`. example: '2024-12-31' country_code: type: string description: ISO 3166-1 alpha-2 country code for geo-targeted search. enum: - 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: type: boolean description: >- Enable fast mode for lower latency. Uses 3 tool call rounds instead of 2 and higher result counts per query. default: false structured_output: type: object nullable: true description: >- 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: type: string nullable: true description: >- Custom system instructions for the AI. Replaces the default research agent prompt. Max 2000 characters. maxLength: 2000 example: You are a medical research assistant. Cite all sources. Error: type: object description: Standard error response. required: - success - error properties: success: type: boolean description: Always `false` for error responses. example: false error: type: string description: Human-readable error message describing what went wrong. example: Invalid request parameters responses: BadRequest: description: The request was malformed or contained invalid parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Invalid parameters value: success: false error: >- Invalid search_type. Must be 'all', 'web', 'proprietary', or 'news' Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Invalid API key value: success: false error: Invalid API key PaymentRequired: description: Insufficient credits or monthly limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Insufficient credits value: success: false error: >- Insufficient credits. Please top up your account at platform.valyu.ai Forbidden: description: The API key does not have permission for this operation. content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Permission denied value: success: false error: API key does not have inference permission RateLimited: description: Too many requests. Slow down and retry after the indicated period. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: description: Maximum requests allowed per window. schema: type: integer X-RateLimit-Remaining: description: Remaining requests in the current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the rate limit window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Rate limit exceeded value: success: false error: >- Rate limit exceeded. Please retry after the Retry-After period. InternalServerError: description: An unexpected error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Internal error value: success: false error: Internal server error. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API key for authentication. Get yours at [platform.valyu.ai](https://platform.valyu.ai). ````