> ## 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. # Get Status > Reference for getting deep research task status via GET /v1/deepresearch/tasks/\{id\}/status. ## OpenAPI ````yaml GET /v1/deepresearch/tasks/{id}/status 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/{id}/status: get: tags: - DeepResearch summary: Get DeepResearch task status and results description: >- Retrieve the current status, progress, and results of a DeepResearch task. Poll this endpoint to track research progress and retrieve the final output. operationId: getDeepResearchStatus parameters: - name: id in: path required: true schema: type: string description: DeepResearch task ID. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 responses: '200': description: Task status and results. content: application/json: schema: $ref: '#/components/schemas/DeepResearchStatusResponse' examples: running: summary: Task in progress value: deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: running query: >- Comprehensive analysis of CRISPR gene therapy clinical trials mode: standard output_formats: - markdown - pdf created_at: '2024-06-15T10:30:00.000Z' public: false progress: current_step: 5 total_steps: 15 completed: summary: Task completed with output value: deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: completed query: >- Comprehensive analysis of CRISPR gene therapy clinical trials mode: standard output_formats: - markdown - pdf created_at: '2024-06-15T10:30:00.000Z' completed_at: '2024-06-15T10:42:00.000Z' public: false output_type: markdown output: >- # CRISPR Gene Therapy Clinical Trials: A Comprehensive Analysis\n\n## Executive Summary\n\nThis report analyzes... sources: - title: 'CRISPR Gene Therapy: A Comprehensive Review' url: https://pubmed.ncbi.nlm.nih.gov/12345678/ snippet: >- CRISPR-based gene therapy has shown remarkable progress... source: pubmed doi: 10.1038/s41586-024-07107-7 word_count: 8500 - title: 'Phase 3 Results: Exa-cel for Sickle Cell Disease' url: https://clinicaltrials.gov/study/NCT04208529 snippet: The pivotal trial demonstrated... source: web word_count: 3200 cost: 0.5 pdf_url: https://storage.valyu.ai/pdfs/a1b2c3d4.pdf images: - image_id: img_chart001 image_type: chart deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 title: CRISPR Trial Phases Distribution image_url: https://storage.valyu.ai/images/img_chart001.png chart_type: bar created_at: '2024-06-15T10:38:00.000Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: DeepResearchStatusResponse: type: object description: Full status and results of a DeepResearch task. required: - deepresearch_id - status - query - 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: >- Current task status. - `queued` - Waiting for capacity - `running` - Research in progress - `awaiting_input` - HITL checkpoint active, waiting for user response - `paused` - HITL checkpoint timed out, state saved, respond anytime to resume - `completed` - Research finished successfully - `failed` - Research failed - `cancelled` - Task was cancelled enum: - queued - running - awaiting_input - paused - completed - failed - cancelled example: completed query: type: string description: The original research query. example: Comprehensive analysis of CRISPR gene therapy clinical trials mode: type: string description: Research mode used for this task. enum: - fast - standard - heavy - max example: standard output_formats: type: array description: Output formats requested for this task. items: oneOf: - type: string enum: - markdown - pdf - toon - type: object example: - markdown - pdf created_at: type: string format: date-time description: ISO 8601 timestamp of task creation. example: '2024-06-15T10:30:00.000Z' public: type: boolean description: Whether the task results are publicly accessible. example: false batch_id: type: string description: Batch ID if this task belongs to a batch. batch_task_id: type: string description: User-provided task ID within a batch. progress: type: object description: Research progress. Present when `status` is `"running"`. properties: current_step: type: integer example: 5 total_steps: type: integer example: 15 output_type: type: string description: Format of the output. Present when `status` is `"completed"`. enum: - markdown - json - toon example: markdown output: description: >- Research output. Markdown string or JSON object depending on `output_type`. Present when `status` is `"completed"` (may be partial on `"failed"` or `"cancelled"`). oneOf: - type: string - type: object additionalProperties: true sources: type: array description: >- Sources used during research. Present when `status` is `"completed"`, `"failed"`, or `"cancelled"`. items: $ref: '#/components/schemas/DeepResearchSource' cost: type: number description: >- Total cost billed for this task in USD (base mode price + any tool surcharges). example: 0.5 cost_breakdown: type: object description: Itemized cost breakdown. Only present when the task has completed. properties: task: type: number description: Base task price for the selected mode. screenshots: type: number description: Screenshot surcharges ($0.05 per URL captured). Omitted if 0. code_execution: type: number description: Code execution surcharges ($0.10 per execution). Omitted if 0. deliverables: type: number description: >- Deliverable surcharges ($0.10 per deliverable after the first). Omitted if 0. required: - task tools: type: object description: Resolved tools configuration for this task. properties: code_execution: type: boolean description: Whether code execution was enabled. screenshots: type: boolean description: Whether screenshots were enabled. charts: type: boolean description: Whether chart generation was enabled. completed_at: type: string format: date-time description: >- ISO 8601 timestamp of task completion. Present when `status` is `"completed"`. example: '2024-06-15T10:35:00.000Z' pdf_url: type: string format: uri description: >- URL to the generated PDF report. Present when `"pdf"` was in `output_formats`. images: type: array description: >- Images generated during research (charts, AI-generated, screenshots). Present when `status` is `"completed"`. items: $ref: '#/components/schemas/DeepResearchImage' deliverables: type: array description: >- Generated deliverable files (CSV, Excel, PowerPoint, Word, PDF). Present when deliverables were requested. items: $ref: '#/components/schemas/DeepResearchDeliverableResult' messages: type: array description: >- Conversation trace of the research agent. Present when `status` is `"running"` or `"completed"`. items: type: object properties: role: type: string content: type: string error: type: string description: Error message. Present when `status` is `"failed"`. hitl_config: type: object description: HITL configuration. Present when HITL was enabled on task creation. properties: planning_questions: type: boolean plan_review: type: boolean source_review: type: boolean outline_review: type: boolean interaction: type: object description: >- Current HITL checkpoint. Present when status is `awaiting_input` or `paused`. properties: interaction_id: type: string description: Unique ID for this interaction. Pass this when responding. type: type: string description: Checkpoint type. enum: - planning_questions - plan_review - source_review - outline_review data: description: Checkpoint-specific data — shape depends on `type`. oneOf: - $ref: '#/components/schemas/HitlPlanningQuestionsData' - $ref: '#/components/schemas/HitlPlanReviewData' - $ref: '#/components/schemas/HitlSourceReviewData' - $ref: '#/components/schemas/HitlOutlineReviewData' created_at: type: integer description: Unix timestamp (ms) when the checkpoint fired. timeout_ms: type: integer description: Timeout duration in milliseconds (default 300000 = 5 minutes). expected_response: type: object description: Schema hint for the expected response shape. additionalProperties: true hitl_history: type: array description: >- History of completed HITL checkpoints. Present after any checkpoint completes. items: type: object properties: interaction_id: type: string type: type: string enum: - planning_questions - plan_review - source_review - outline_review created_at: type: integer description: When the checkpoint fired (ms). responded_at: type: integer description: When the user responded (ms). Absent if timed out. auto_continued: type: boolean description: True if timed out, false if user responded. response: type: object description: The user's response. Absent if timed out. additionalProperties: true DeepResearchSource: type: object description: A source used during research. properties: title: type: string description: Title of the source document. example: 'CRISPR Gene Therapy: A Comprehensive Review' url: type: string format: uri description: URL of the source. example: https://pubmed.ncbi.nlm.nih.gov/12345678/ snippet: type: string description: Relevant text excerpt from the source. description: type: string description: Brief description or snippet from the source. source: type: string description: Source identifier. price: type: number description: Cost in USD for accessing this source. doi: type: string description: DOI identifier (academic sources). word_count: type: integer description: Word count of the source document. DeepResearchImage: type: object description: An image generated during research (chart, AI-generated, or screenshot). required: - image_id - image_type - title - image_url - created_at properties: image_id: type: string description: Unique image identifier. example: img_a1b2c3d4e5f6 image_type: type: string enum: - chart - ai_generated - screenshot description: Type of image. example: chart title: type: string description: Image title. example: Clinical Trial Phase Distribution description: type: string description: Image description. example: Bar chart showing distribution of CRISPR trials across phases image_url: type: string format: uri description: URL to access the image. example: https://storage.valyu.ai/images/img_a1b2c3d4e5f6.png created_at: type: integer description: Unix timestamp (milliseconds) of image creation. example: 1718444520000 source_url: type: string format: uri description: >- Original web page URL. Only present when `image_type` is `"screenshot"`. example: https://example.com/dashboard captured_at: type: integer description: >- Unix timestamp (milliseconds) when the screenshot was taken. Only present when `image_type` is `"screenshot"`. example: 1718444520000 chart_type: type: string enum: - line - bar - area - pie - doughnut - radar - scatter - horizontalBar - heatmap - boxplot - stackedBar - stackedArea - histogram - waterfall - timeline - bubble description: Chart type. Only present when `image_type` is `"chart"`. example: bar x_axis_label: type: string description: X-axis label. Only present for chart images. example: Trial Phase y_axis_label: type: string description: Y-axis label. Only present for chart images. example: Number of Trials data_series: type: array description: Chart data series. Only present when `image_type` is `"chart"`. items: type: object required: - name - data properties: name: type: string description: Series name shown in the legend. data: type: array items: type: object required: - x - 'y' properties: x: oneOf: - type: string - type: number description: X-axis value (category or numeric). 'y': type: number description: Y-axis value. y2: type: number description: >- End value for `timeline` charts (y = start epoch ms, y2 = end epoch ms). z: type: number description: Bubble size for `bubble` charts. values: type: array items: type: number description: >- Raw data points for `boxplot` charts (library computes quartiles). line_style: type: string enum: - solid - dashed - dotted description: Line style override for `line`/`area` charts. DeepResearchDeliverableResult: type: object description: A generated deliverable file from a DeepResearch task. required: - id - request - type - status - title - url - s3_key - created_at properties: id: type: string description: Unique deliverable identifier. example: del_a1b2c3d4e5f6 request: type: string description: Original deliverable request description. example: >- Extract all company names, founding years, and revenue data into a spreadsheet type: type: string enum: - csv - xlsx - pptx - docx - pdf - unknown description: Deliverable file type. example: xlsx status: type: string enum: - completed - failed description: Generation status. example: completed title: type: string description: Generated filename or title. example: company_data.xlsx description: type: string description: Description of the deliverable content. example: >- Spreadsheet containing 25 companies with founding years and revenue data url: type: string format: uri description: Token-signed URL to download the file. example: >- https://storage.valyu.ai/deliverables/del_a1b2c3d4e5f6.xlsx?token=... s3_key: type: string description: S3 storage key. example: deliverables/org_123/del_a1b2c3d4e5f6.xlsx row_count: type: integer description: Number of rows. Only present for CSV/XLSX. example: 25 column_count: type: integer description: Number of columns. Only present for CSV/XLSX. example: 5 error: type: string description: Error message. Only present when `status` is `"failed"`. created_at: type: integer description: Unix timestamp (milliseconds) of creation. example: 1718444640000 HitlPlanningQuestionsData: type: object title: Planning Questions Data description: >- Interaction data for the `planning_questions` checkpoint. Contains clarifying questions the agent wants answered before starting research. required: - questions properties: questions: type: array description: List of clarifying questions. items: type: object required: - question properties: question: type: string description: The question text. example: What geographic regions should the research focus on? context: type: string description: Optional context explaining why this question matters. example: >- The query mentions global markets — narrowing scope improves depth HitlPlanReviewData: type: object title: Plan Review Data description: >- Interaction data for the `plan_review` checkpoint. Contains the research plan for user approval. required: - plan properties: plan: type: string description: The proposed research plan. example: >- I'll research this topic by first examining market size data, then analyzing the competitive landscape... estimated_steps: type: integer description: Estimated number of research steps. example: 15 research_areas: type: array description: Key areas the research will cover. items: type: string example: - Market size analysis - Competitive landscape - Regulatory environment HitlSourceReviewData: type: object title: Source Review Data description: >- Interaction data for the `source_review` checkpoint. Contains sources grouped by domain for user filtering. required: - domains - total_sources properties: domains: type: array description: Sources grouped by domain. items: type: object required: - domain - source_count - avg_relevance_score - sources - ai_recommendation properties: domain: type: string description: Domain name. example: sec.gov source_count: type: integer description: Number of sources from this domain. example: 8 avg_relevance_score: type: number description: Average relevance score (0-1). example: 0.87 sources: type: array description: Individual sources from this domain. items: type: object properties: source_id: type: integer title: type: string url: type: string format: uri relevance_score: type: number ai_recommendation: type: string description: AI's recommendation for this domain. enum: - include - exclude example: include total_sources: type: integer description: Total number of sources across all domains. example: 42 HitlOutlineReviewData: type: object title: Outline Review Data description: >- Interaction data for the `outline_review` checkpoint. Contains the report outline for user approval. required: - outline - sections properties: outline: type: string description: The full outline as text. example: |- 1. Introduction 2. Market Analysis 3. Competitive Landscape 4. Conclusion sections: type: array description: Structured list of sections. items: type: object required: - title - description properties: title: type: string description: Section title. example: Market Analysis description: type: string description: What this section covers. example: Detailed market size and growth analysis estimated_length: type: string description: Expected length of this section. enum: - short - medium - long example: long 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: 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 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 NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: example: summary: Resource not found value: success: false error: Task not found 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). ````