> ## 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. # List Batch Tasks > Reference for listing tasks in a batch via GET /v1/deepresearch/batches/{id}/tasks. ## OpenAPI ````yaml GET /v1/deepresearch/batches/{id}/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/batches/{id}/tasks: get: tags: - Batches summary: List tasks in a batch description: >- Retrieve tasks within a batch with optional status filtering and cursor-based pagination. Use `include_output=true` to get full output, sources, images, and cost for each task. When `include_output` is false (default), returns a lightweight listing with status only. operationId: listBatchTasks parameters: - name: id in: path required: true schema: type: string description: Batch ID. - name: status in: query schema: type: string enum: - queued - running - completed - failed - cancelled description: Filter tasks by status. - name: limit in: query schema: type: integer minimum: 1 description: Maximum number of tasks to return. - name: last_key in: query required: false schema: type: string nullable: true description: >- Pagination cursor. Omit on first request. Pass the `last_key` value from a previous response to fetch the next page. - name: include_output in: query required: false schema: type: boolean default: false example: true description: >- Include full output, sources, images, and cost for each task. When false (default), returns lightweight task listing with status only. responses: '200': description: Paginated list of batch tasks. content: application/json: schema: $ref: '#/components/schemas/BatchTaskListResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: BatchTaskListResponse: type: object required: - batch_id - tasks - pagination properties: batch_id: type: string description: ID of the batch these tasks belong to. example: batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890 tasks: type: array description: Array of tasks in the batch. items: $ref: '#/components/schemas/BatchTask' pagination: description: Pagination metadata. type: object required: - count - has_more properties: count: type: integer description: Number of tasks returned. example: 10 last_key: type: string nullable: true description: >- Cursor for the next page. Pass as `last_key` query parameter. `null` if no more results. has_more: type: boolean example: false BatchTask: type: object description: >- A task within a batch. When `include_output=true` is passed to the list tasks endpoint, additional fields (output_type, output, sources, images, pdf_url, deliverables, error, cost) are included. required: - deepresearch_id - status - query - created_at properties: task_id: type: string description: User-provided task ID within the batch. deepresearch_id: type: string description: Unique ID for the research task. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: type: string description: Current task status. enum: - queued - running - completed - failed - cancelled example: completed query: type: string description: The research query for this task. example: Analyze Tesla Q4 2024 earnings created_at: type: string format: date-time description: ISO 8601 timestamp of task creation. example: '2024-06-15T10:30:00.000Z' completed_at: type: string format: date-time description: >- ISO 8601 timestamp of task completion. Only present when task is done. output_type: type: string enum: - markdown - json - toon description: >- Format of the output. Only present when `include_output=true` and task is completed. output: description: >- Research output. Markdown string, parsed JSON object, or null. Only present when `include_output=true`. example: |- ## Tesla Q4 2025 Earnings Analysis ... sources: type: array description: >- Sources cited in the research output. Only present when `include_output=true` and task is completed. items: type: object images: type: array description: >- Charts and images generated during research. Only present when `include_output=true` and task produced images. items: type: object pdf_url: type: string description: >- URL to the PDF version of the report. Only present when `include_output=true` and PDF output was requested. example: https://api.valyu.ai/v1/deepresearch/tasks/52fafd51/pdf deliverables: type: array description: >- Generated deliverables (XLSX, PPTX, DOCX). Only present when `include_output=true` and deliverables were produced. items: type: object error: type: string nullable: true description: >- Error message. Only present when `include_output=true` for failed tasks. example: Task exceeded maximum execution time cost: type: number description: Cost of this task in USD. Only present when `include_output=true`. example: 1 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 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). ````