> ## 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. # Create Task > Reference for creating a new deep research task via POST /v1/deepresearch/tasks. ## OpenAPI ````yaml POST /v1/deepresearch/tasks 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/deepresearch/tasks: post: tags: - DeepResearch summary: Create a DeepResearch task description: >- Start an async research task that performs comprehensive, multi-step research. The research agent searches multiple sources, analyzes content, executes code, and generates a detailed report with citations. Tasks run in the background and typically take 1-10 minutes depending on the `mode`. Poll the status endpoint or use webhooks to get results. operationId: createDeepResearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeepResearchCreateRequest' examples: basic: summary: Basic research task value: query: >- Comprehensive analysis of CRISPR gene therapy clinical trials in 2024 mode: standard advanced: summary: Advanced research with PDF output and file attachments value: query: Compare efficacy data across Phase 3 CRISPR trials mode: heavy strategy: >- Focus on safety profiles, patient outcomes, and regulatory pathways output_formats: - markdown - pdf search: search_type: proprietary included_sources: - medical start_date: '2023-01-01' urls: - https://clinicaltrials.gov/study/NCT12345678 webhook_url: https://your-app.com/webhooks/deepresearch structured: summary: Structured JSON output value: query: Top 10 AI companies by funding raised in 2024 mode: fast output_formats: - type: object properties: companies: type: array items: type: object properties: name: type: string funding_millions: type: number focus_area: type: string responses: '202': description: Research task created and queued. content: application/json: schema: $ref: '#/components/schemas/DeepResearchCreateResponse' examples: running: summary: Task started immediately value: deepresearch_id: f992a8ab-4c91-4322-905f-190107bd5a5b status: running mode: standard created_at: '2024-06-15T10:30:00.000Z' metadata: project: drug-discovery public: false queued: summary: Task queued (capacity limit) value: deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: queued mode: heavy created_at: '2024-06-15T10:30:00.000Z' public: false message: 'Task queued. Current position: 3' webhook_secret: >- a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678 '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: DeepResearchCreateRequest: type: object required: - query additionalProperties: false description: Request to create a DeepResearch task. properties: query: type: string description: >- The research query or question. Use `query` (preferred) or `input` (deprecated). Maximum 25,000 characters. maxLength: 25000 example: >- Comprehensive analysis of CRISPR gene therapy clinical trials in 2024 input: type: string deprecated: true description: '**Deprecated.** Use `query` instead.' mode: type: string description: |- Research mode controlling depth and cost. | Mode | Price | Best For | Max Steps | | --- | --- | --- | --- | | `fast` | $0.10 | Quick queries, batch processing | 10 | | `standard` | $0.50 | Balanced research | 15 | | `heavy` | $2.50 | Complex topics requiring deep analysis | 15 | | `max` | $15.00 | Exhaustive research with maximum quality | 25 | enum: - fast - standard - heavy - max default: standard example: standard model: type: string deprecated: true description: '**Deprecated.** Use `mode` instead.' enum: - fast - standard - heavy - max strategy: type: string deprecated: true description: >- **Deprecated.** Use `research_strategy` instead. Natural language strategy to guide the research agent's approach. example: Focus on Phase 3 trials and compare efficacy data across studies research_strategy: type: string description: >- Natural language strategy to guide the research phase. Controls how the agent searches, what sources to prioritize, and research methodology. Combined length of `research_strategy` and `report_format` must not exceed 15,000 characters. maxLength: 15000 example: Focus on Phase 3 trials and compare efficacy data across studies report_format: type: string description: >- Natural language instructions for the output format. Has highest priority and overrides default formatting. Controls structure, style, length, and presentation of the final report. Combined length of `research_strategy` and `report_format` must not exceed 15,000 characters. maxLength: 15000 example: >- Write a 2-page executive summary with bullet points and a comparison table search: $ref: '#/components/schemas/SearchConfig' urls: type: array description: URLs to include in the research context. Max 10. items: type: string format: uri maxItems: 10 example: - https://clinicaltrials.gov/study/NCT12345678 files: type: array description: Files to analyze as part of the research. Max 10. items: $ref: '#/components/schemas/FileAttachment' maxItems: 10 output_formats: type: array description: |- Desired output formats. Defaults to `["markdown"]`. - `"markdown"` - Markdown report (default) - `"pdf"` - PDF document (can combine with `"markdown"`) - `"toon"` - Visual toon-style output - JSON Schema object - Structured JSON output JSON schema output cannot be combined with markdown or PDF. items: oneOf: - type: string enum: - markdown - pdf - toon - type: object description: JSON Schema for structured output. default: - markdown example: - markdown - pdf metadata: type: object description: Arbitrary key-value metadata to attach to the task. additionalProperties: oneOf: - type: string - type: number - type: boolean example: project: drug-discovery priority: high mcp_servers: type: array description: MCP servers to provide additional tools during research. Max 5. items: $ref: '#/components/schemas/MCPServerConfig' maxItems: 5 code_execution: type: boolean description: >- Deprecated: use tools.code_execution instead. Enable code execution capability. default: false deprecated: true tools: type: object description: >- Controls which optional tools the research agent can use. All tools default to false. properties: code_execution: type: boolean description: Enable code execution in a sandboxed Python environment. default: false screenshots: type: boolean description: Enable visual screenshot capture of web pages. default: false charts: type: boolean description: >- Enable chart and graph generation embedded in the final report. Free, no per-call surcharge. default: false previous_reports: type: array description: DeepResearch task IDs to use as context for this task. Max 3. items: type: string maxItems: 3 example: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 webhook_url: type: string format: uri description: >- HTTPS URL to receive a webhook POST when the task completes. Signed with HMAC-SHA256. example: https://your-app.com/webhooks/deepresearch alert_email: oneOf: - type: string format: email description: Email address to notify on completion. - type: object required: - email properties: email: type: string format: email description: >- Email address to notify on completion. Must belong to your organization. custom_url: type: string format: uri description: >- Custom URL template for the report link in the email. Must contain {id} which gets replaced with the deepresearch task ID. example: https://your-app.com/reports/{id} description: >- Email notification on completion. Pass a string (email address) or an object with email and optional custom_url. The custom_url must contain {id} which gets replaced with the task ID. Email must belong to your organization. deliverables: type: array description: >- Deliverable files to generate from the research (e.g. Excel reports, presentations). Max 10. items: description: >- A deliverable to generate from the research. Can be a string (natural language description, max 500 chars) or a structured object. oneOf: - type: string maxLength: 500 description: Natural language description of the deliverable. - type: object required: - type - description properties: type: type: string enum: - csv - xlsx - pptx - docx - pdf description: File format for the deliverable. description: type: string maxLength: 500 description: Description of what the deliverable should contain. columns: type: array items: type: string description: >- Suggested column names for tabular deliverables (csv, xlsx). schema: type: object description: JSON Schema for structured deliverables. maxItems: 10 hitl: type: object description: >- Human-in-the-loop configuration. Enable checkpoints that pause execution at key decision points. Not available for batch requests. properties: planning_questions: type: boolean description: Pause before research to ask clarifying questions. default: false plan_review: type: boolean description: Pause after planning for user to review the research plan. default: false source_review: type: boolean description: Pause after research for user to filter sources by domain. default: false outline_review: type: boolean description: Pause after source review for user to review the report outline. default: false DeepResearchCreateResponse: type: object description: Response after creating a DeepResearch task. required: - deepresearch_id - status - mode - created_at properties: deepresearch_id: type: string description: Unique identifier for the research task. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: type: string description: >- Initial task status. `"running"` if started immediately, `"queued"` if waiting for capacity. enum: - running - queued example: running mode: type: string description: Research mode used for this task. enum: - fast - standard - heavy - max example: standard created_at: type: string format: date-time description: ISO 8601 timestamp of task creation. example: '2024-06-15T10:30:00.000Z' metadata: type: object description: Metadata attached to the task. additionalProperties: true public: type: boolean description: Whether the task is publicly accessible. example: false webhook_secret: type: string description: >- HMAC-SHA256 secret for verifying webhook payloads. Only present when `webhook_url` was provided. message: type: string description: Status message. Present when task is queued. SearchConfig: type: object description: Search configuration for DeepResearch tasks. properties: search_type: type: string enum: - all - web - proprietary description: Controls which data sources are searched. default: all included_sources: type: array description: Sources to include. Max 20 items. items: type: string maxItems: 20 excluded_sources: type: array description: Sources to exclude. Max 20 items. items: type: string maxItems: 20 source_biases: type: object description: >- Bias values for specific sources to influence ranking (-5 to +5). Applied to every search call during research. additionalProperties: type: integer minimum: -5 maximum: 5 country_code: type: string 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 description: Country code for geo-targeted search. start_date: type: string format: date description: 'Filter results from this date. Format: `YYYY-MM-DD`.' end_date: type: string format: date description: >- Filter results until this date. Format: `YYYY-MM-DD`. Must be >= `start_date`. FileAttachment: type: object description: A file to include in the research task. required: - data - filename - mediaType properties: data: type: string description: >- File content as a data URL. Format: `data:;base64,`. example: data:application/pdf;base64,JVBERi0xLjQK... filename: type: string description: Original filename. example: research_paper.pdf mediaType: type: string description: MIME type of the file. example: application/pdf context: type: string description: >- Optional context about the file to guide the research agent. Maximum 10,000 characters. maxLength: 10000 MCPServerConfig: type: object description: >- MCP (Model Context Protocol) server configuration for tool access during research. required: - url properties: url: type: string format: uri description: HTTP/HTTPS URL of the MCP server. example: https://mcp.example.com/tools name: type: string description: Display name for the MCP server. tool_prefix: type: string description: Prefix for tool names. Defaults to the server hostname. auth: type: object description: Authentication configuration. properties: type: type: string enum: - bearer - header - none description: Authentication type. token: type: string description: Bearer token (when `type` is `"bearer"`). headers: type: object description: Custom headers (when `type` is `"header"`). additionalProperties: type: string allowed_tools: type: array description: >- Whitelist of tool names to expose. If omitted, all tools are available. items: type: string 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). ````