> ## 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. # Search > Reference for the Valyu Search endpoint to search the web, research, and proprietary datasets via POST /v1/search. ## OpenAPI ````yaml POST /v1/search 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/search: post: tags: - Search summary: Search across web and proprietary data sources description: >- Search the web, academic journals, financial databases, and 36+ proprietary data sources. Returns ranked results with extracted content, ready for RAG pipelines and AI agents. Results are ranked by relevance using Voyage AI reranking (unless `fast_mode` is enabled). You only pay for results returned - pricing is CPM-based (cost per mille tokens). operationId: search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' examples: basic: summary: Basic web search value: query: latest developments in quantum computing max_num_results: 5 academic: summary: Academic paper search value: query: CRISPR gene editing clinical trials 2024 search_type: proprietary max_num_results: 10 included_sources: - medical filtered: summary: Source-filtered search with date range value: query: climate change impact on agriculture included_sources: - valyu/valyu-arxiv - valyu/valyu-pubmed - valyu/valyu-biorxiv start_date: '2024-01-01' end_date: '2024-12-31' max_num_results: 10 fast: summary: Low-latency web search value: query: Tesla stock price today fast_mode: true max_num_results: 5 responses: '200': description: Search completed successfully with results. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' examples: success: summary: Successful search with web and proprietary results value: success: true error: null tx_id: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890 query: latest developments in quantum computing results: - id: https://arxiv.org/abs/2024.12345 title: >- Quantum Computing Breakthrough: New Error Correction Method url: https://arxiv.org/abs/2024.12345 content: >- Researchers at MIT have developed a revolutionary quantum error correction method that reduces qubit errors by 99.9%... description: >- Major breakthrough in quantum error correction methodology source: web price: 0.0015 length: 15420 image_url: null relevance_score: 0.95 data_type: unstructured source_type: website publication_date: '2024-06-15' - id: valyu/valyu-arxiv/2401.12345 title: Advances in Topological Quantum Computing url: https://arxiv.org/abs/2401.12345 content: >- We present a novel approach to topological quantum error correction... description: >- Topological approaches to fault-tolerant quantum computation source: valyu/valyu-arxiv price: 0.0005 length: 28000 image_url: null relevance_score: 0.89 data_type: unstructured source_type: paper publication_date: '2024-01-15' doi: 10.48550/arXiv.2401.12345 authors: - J. Smith - A. Chen - M. Kumar results_by_source: web: 3 proprietary: 2 total_deduction_dollars: 0.0075 total_characters: 45230 fast_mode: summary: Fast mode search (web only, no reranking) value: success: true error: null tx_id: tx_fast12345-6789-abcd-ef01-234567890abc query: Tesla stock price today results: - id: https://fred.stlouisfed.org/series/TSLA title: Tesla, Inc. (TSLA) Stock Price, News, Quote & History url: https://fred.stlouisfed.org/series/TSLA content: Tesla Inc (TSLA) stock price... source: web price: 0.0015 length: 5200 data_type: unstructured source_type: website results_by_source: web: 5 total_deduction_dollars: 0.0075 total_characters: 26000 '206': description: >- Partial success - some sources failed or no results found, but the request was processed. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '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: SearchRequest: type: object required: - query additionalProperties: false description: Search request parameters. properties: query: type: string description: The search query to execute. Supports natural language queries. example: latest developments in quantum computing max_num_results: type: integer description: >- Maximum number of results to return. Higher limits (up to 100) available on request. default: 5 minimum: 1 maximum: 20 example: 10 search_type: type: string description: >- Controls which data sources are searched. - `all` - Web and proprietary sources (default). An LLM router selects the best sources for your query. - `web` - Web search only. Best for current events and general topics. - `proprietary` - Academic, financial, and premium sources only. Best for research and technical analysis. - `news` - News articles only. Best for recent news and current events. enum: - all - web - proprietary - news default: all example: all max_price: type: number description: >- Maximum budget in CPM (cost per mille/thousand tokens). When not set, automatically calculated based on `max_num_results` and `search_type` with a minimum floor of 20 CPM. minimum: 0 exclusiveMinimum: true example: 20 relevance_threshold: type: number description: >- Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out. default: 0.5 minimum: 0 maximum: 1 example: 0.5 included_sources: type: array description: >- Sources to include in the search. Accepts: - Domain names or URLs for web filtering (e.g. `"arxiv.org"`, `"https://arxiv.org"`) - Dataset identifiers for proprietary sources (e.g. `"valyu/valyu-arxiv"`) - Preset names that expand to source groups: `"finance"`, `"medical"`, `"transportation"`, `"politics"`, `"legal"`, `"health"`, `"genomics"`, `"chemistry"`, `"physics"` - `"web"` keyword to explicitly include web search alongside proprietary sources - `"collection:NAME"` to reference a saved source collection items: type: string example: - valyu/valyu-arxiv - valyu/valyu-pubmed excluded_sources: type: array description: >- Sources to exclude from the search. Same format as `included_sources` except presets are not supported. items: type: string example: - reddit.com source_biases: type: object description: >- Bias values for specific sources to influence ranking without hard filtering. Keys are domains (e.g., 'nasa.gov') or URL paths (e.g., 'nih.gov/research'). Values are integers from -5 (strong demotion) to +5 (strong boost). Most specific path match wins. additionalProperties: type: integer minimum: -5 maximum: 5 nullable: true example: nasa.gov: 5 noaa.gov: 3 nih.gov: 1 example.com: -4 instructions: type: string description: >- Natural language instructions to help rank results by relevance to user intent. Acts as a system prompt for the search. Max 500 characters. Ignored when fast_mode is true. maxLength: 500 example: Focus on oncology clinical trials from 2023 onwards category: type: string deprecated: true description: >- **Deprecated.** Use `instructions` instead. Falls back to this value if `instructions` is not set. maxLength: 500 is_tool_call: type: boolean description: >- Indicates whether this request originates from an AI tool call. Affects query rewriting behavior. default: true response_length: description: |- Controls the maximum character length of content per result. - `"short"` - 25,000 characters (default) - `"medium"` - 50,000 characters - `"large"` - 100,000 characters - `"max"` - No limit - Any positive integer for a custom character limit oneOf: - type: string enum: - short - medium - large - max - type: integer minimum: 1 default: short example: short start_date: type: string format: date description: >- Filter results published on or after this date. Format: `YYYY-MM-DD`. If set without `end_date`, defaults to today. example: '2024-01-01' end_date: type: string format: date description: >- Filter results published on or before this date. Format: `YYYY-MM-DD`. If set without `start_date`, defaults to `1900-01-01`. example: '2024-12-31' country_code: type: string description: ISO 3166-1 alpha-2 country code for geo-targeted web search results. 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 example: US fast_mode: type: boolean description: >- Bypass LLM query rewriting and reranking for lower latency. Forces web-only search. Cannot be used with `search_type: "proprietary"`. default: false url_only: type: boolean description: >- Return only URLs without full content extraction. Only available when `search_type` is `"web"` or `"news"`. Skips reranking. default: false SearchResponse: type: object description: Search response containing results and metadata. required: - success - tx_id - query - results - results_by_source - total_deduction_dollars - total_characters properties: success: type: boolean description: Whether the search completed successfully. example: true error: type: string nullable: true description: >- Error or warning message. May be non-empty even on successful responses if some sources had issues. example: null tx_id: type: string description: Transaction ID for tracking and support. example: tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890 query: type: string description: The original query as submitted. example: latest developments in quantum computing results: type: array description: Search results ordered by relevance. items: $ref: '#/components/schemas/SearchResult' results_by_source: type: object description: Count of results broken down by source type. properties: web: type: integer description: Number of web results. example: 5 proprietary: type: integer description: Number of proprietary results. example: 3 example: web: 5 proprietary: 3 total_deduction_dollars: type: number description: Total cost charged for this search in USD. example: 0.0075 total_characters: type: integer description: Sum of all result content lengths in characters. example: 45230 warnings: type: array description: >- Warning messages, if any (e.g. collection resolution warnings). Only present when warnings exist. items: type: string SearchResult: type: object description: A single search result with extracted content. required: - id - title - url - content - source - price - length - data_type - source_type properties: id: type: string description: Unique identifier for this result (typically the URL). example: https://arxiv.org/abs/2024.12345 title: type: string description: Title of the source document. example: 'Quantum Computing Breakthrough: New Error Correction Method' url: type: string format: uri description: URL of the source document. example: https://arxiv.org/abs/2024.12345 content: type: string description: >- Extracted text content in markdown format, truncated to `response_length`. example: >- Researchers at MIT have developed a revolutionary quantum error correction method... description: type: string nullable: true description: Short description or meta summary of the document. example: Major breakthrough in quantum error correction methodology source: type: string description: >- Source identifier. `"web"` for web results, or a proprietary source name. example: web price: type: number description: Cost in USD for this individual result. example: 0.0015 length: type: integer description: Character count of the `content` field. example: 15420 image_url: nullable: true description: >- Image URLs associated with this result, keyed by index. `null` if no images. oneOf: - type: object additionalProperties: type: string format: uri - type: string format: uri example: '0': https://example.com/image.jpg relevance_score: type: number description: Relevance score from reranking (0.0-1.0). Higher is more relevant. minimum: 0 maximum: 1 example: 0.92 data_type: type: string description: Format of the content field. enum: - unstructured - structured example: unstructured source_type: type: string description: |- Classification of the source. - `website` - General web page - `forum` - Forum or discussion thread - `paper` - Academic paper - `data` - Structured data source - `report` - Report or analysis - `health_data` - Healthcare data - `clinical_trial` - Clinical trial record - `drug_label` - FDA drug label - `grants` - Research grant enum: - website - forum - paper - data - report - health_data - clinical_trial - drug_label - grants example: website publication_date: type: string description: Publication date in `YYYY-MM-DD` format, or empty string if unknown. example: '2024-06-15' doi: type: string description: DOI identifier (academic results only). example: 10.1038/s41586-024-07107-7 citation: type: string description: Citation text (academic results only). example: '' citation_count: type: integer description: Number of citations (academic results only). example: 42 authors: type: array description: Author names (academic results only). items: type: string example: - J. Smith - A. Chen references: type: string description: References text (academic results only). example: '' metadata: type: object description: >- Additional structured metadata (financial and specialized results only). additionalProperties: true 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). ````