> ## 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 Versions

> Reference for listing report versions on a DeepResearch task via GET /v1/deepresearch/tasks/{id}/versions.

List every version of a DeepResearch task, along with the current `head` version number. Every applied edit and every restore appends a new version; prior versions are never deleted.

Each version entry reports its `kind` (`original`, `edit`, or `restore`), `target`, `created_at`, `edit_id`, `instruction`, `summary`, `stats`, `is_head`, and `pdf_url`.

To read the full content, sources, PDF, and deliverable files of any specific version, call [Get status](https://docs.valyu.ai/api-reference/endpoint/deepresearch-status.md) with `?version=N`. Asset and deliverable file routes (`GET /v1/deepresearch/tasks/{id}/assets/report.pdf?version=N` and deliverable file routes) also accept `?version=N`. To roll back to an earlier version, use [Restore version](https://docs.valyu.ai/api-reference/endpoint/deepresearch-versions-restore.md). Only the task owner can inspect version history.


## OpenAPI

````yaml GET /v1/deepresearch/tasks/{id}/versions
openapi: 3.0.3
info:
  title: Valyu API
  version: 2.3.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, genomics, and 40+ 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 |

    | **Workflows** (Beta) | `GET /v1/workflows` | Templated, versioned
    DeepResearch for repeatable knowledge work |

    | **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 (the
    lowercase `x-api-key` form is also accepted). Get your key at
    [platform.valyu.ai](https://platform.valyu.ai).


    ```

    X-API-Key: your_api_key_here

    ```


    ## Pricing


    Pay per use in credits. One credit balance covers every API.

    - **Search**: priced per result returned. Web and news results use 0.1
    credits each (100 per 1,000 results). arXiv, PubMed, bioRxiv and medRxiv use
    0.05 credits each (50 per 1,000). Other datasets have their own price per
    1,000 results, listed in `GET /v1/datasources` (`pricing.cpm`).

    - **Contents**: 0.2 credits per successfully extracted URL. Any AI
    processing (a text summary or structured extraction through `summary`)
    brings the price to 0.6 credits per URL in total, the same for both. Failed
    URLs are free.

    - **Answer**: no per-request fee. You pay for the search, content extraction
    and AI processing each answer uses, reported in
    `cost.total_deduction_dollars`.

    - **DeepResearch**: fixed price per task by mode: instant 8 credits, fast
    25, standard 100, heavy 500, max 2,500, plus tool add-ons.


    Every plan includes web search and open academic sources. Paid plans unlock
    specialist sources such as SEC filings, clinical trials, patents and
    genomics. See [pricing](https://docs.valyu.ai/pricing) for plans and free
    credits.


    ## Rate limits


    Limits apply per organisation: 10 requests per second with bursts up to 20,
    and 86,400 requests per day by default. Enterprise plans can raise them. A
    request over the limit is currently rejected with `403 Forbidden` and the
    body `{"error": "Forbidden", "message": "Access denied - API key is invalid,
    disabled, or revoked"}`. If a key that otherwise works starts receiving 403
    under load, reduce concurrency and retry with exponential backoff.


    ## SDKs


    - [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu`

    - [TypeScript SDK](https://www.npmjs.com/package/valyu-js) - `npm install
    valyu-js`
  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: Workflows
    description: >-
      **Beta.** Templated, versioned DeepResearch for repeatable knowledge work
      - earnings previews, diligence reads, market sizings. A workflow bundles a
      prompt template with typed variables, a research strategy, report format,
      deliverables, tools, and a recommended mode. Workflows are immutably
      versioned; runs can pin a version. Two scopes exist: your organization's
      private workflows and curated Valyu workflows available to everyone. Run a
      workflow by passing `workflow_id` + `workflow_params` to `POST
      /v1/deepresearch/tasks` - same auth, billing, and task lifecycle as
      freeform DeepResearch.
    externalDocs:
      description: Workflows Guide (Beta)
      url: https://docs.valyu.ai/guides/workflows
  - 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}/versions:
    get:
      tags:
        - DeepResearch
      summary: List task versions
      description: >-
        List all versions of a DeepResearch task (`original`, `edit`, and
        `restore`) along with the current `head` version number. Read a specific
        version's full output, sources, PDF, and files with `GET
        /v1/deepresearch/tasks/{id}/status?version=N`. Only the task owner can
        list versions.
      operationId: listDeepResearchVersions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Version history for the task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchVersionListResponse'
              examples:
                history:
                  summary: Task with original, edited, and restored versions
                  value:
                    deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    head: 2
                    versions:
                      - version: 2
                        kind: edit
                        target:
                          kind: report
                        created_at: '2026-11-19T14:20:09.000Z'
                        edit_id: ed_01j9x4k2m8n7p3q5r6s8t0v2w4
                        instruction: >-
                          Cut the executive summary to 3 bullets and add the Q3
                          revenue figure with its citation.
                        summary: >-
                          Condensed the Executive Summary to 3 bullets and added
                          the Q3 revenue figure with citation [14].
                        stats:
                          replacements: 1
                          chars_changed: 412
                          citations_added: 1
                        is_head: true
                        pdf_url: >-
                          https://api.valyu.ai/v1/deepresearch/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assets/report.pdf?version=2
                      - version: 1
                        kind: original
                        target:
                          kind: report
                        created_at: '2026-11-19T14:12:00.000Z'
                        edit_id: null
                        instruction: null
                        summary: null
                        stats: null
                        is_head: false
                        pdf_url: >-
                          https://api.valyu.ai/v1/deepresearch/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assets/report.pdf?version=1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    DeepResearchVersionListResponse:
      type: object
      description: Version history for a DeepResearch task.
      required:
        - deepresearch_id
        - head
        - versions
      properties:
        deepresearch_id:
          type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        head:
          type: integer
          minimum: 1
          description: Current head version number.
          example: 2
        versions:
          type: array
          description: All versions of the task.
          items:
            $ref: '#/components/schemas/DeepResearchVersionItem'
    DeepResearchVersionItem:
      type: object
      description: A single version entry in a task's version history.
      required:
        - version
        - kind
        - created_at
        - is_head
      properties:
        version:
          type: integer
          minimum: 1
          description: Version number.
        kind:
          type: string
          enum:
            - original
            - edit
            - restore
          description: How this version was created.
        target:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditTarget'
          description: Target edited to create this version, when applicable.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this version was created.
        edit_id:
          type: string
          nullable: true
          description: Edit ID that created this version, when `kind` is `edit`.
        instruction:
          type: string
          nullable: true
          description: Edit instruction that created this version, when `kind` is `edit`.
        summary:
          type: string
          nullable: true
          description: Summary of changes in this version.
        stats:
          type: object
          nullable: true
          additionalProperties: true
          description: Edit statistics for this version, when available.
        is_head:
          type: boolean
          description: Whether this version is the current head.
        pdf_url:
          type: string
          format: uri
          nullable: true
          description: URL to the PDF for this version, when available.
    Error:
      type: object
      description: >-
        Error response. Every error body has `error`. Search, Contents, Answer
        and Datasources errors usually also carry `success: false`. Errors
        returned before a request reaches the endpoint (missing, invalid or
        disabled keys, rate limits) and DeepResearch errors have no `success`
        field. Some errors add a machine-readable `code` and a `recovery`
        object.
      required:
        - error
      properties:
        success:
          type: boolean
          description: '`false` when present.'
          example: false
        error:
          type: string
          description: >-
            Error message, or a machine-readable code for some errors (for
            example `invalid_scope_policy`, or `rate_limited` on a `429`).
          example: Invalid request parameters
        message:
          type: string
          description: >-
            Human-readable detail. Present on errors returned before the request
            reaches the endpoint.
        code:
          type: string
          description: >-
            Stable machine-readable error code, when available. Branch on this
            rather than on the message text.
          example: insufficient_credits
        recovery:
          type: object
          description: Links or details that help resolve the error, when available.
          additionalProperties: true
        transaction_id:
          type: string
          description: Transaction ID for support, when available.
    DeepResearchEditTarget:
      description: >-
        What to edit: the written report (`{"kind": "report"}`, default) or a
        specific deliverable file (`{"kind": "deliverable", "deliverable_id":
        "f_01"}`).
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - kind
          properties:
            kind:
              type: string
              enum:
                - report
              description: Edit the written markdown report.
        - type: object
          additionalProperties: false
          required:
            - kind
            - deliverable_id
          properties:
            kind:
              type: string
              enum:
                - deliverable
              description: Edit one of the task's generated deliverable files.
            deliverable_id:
              type: string
              description: >-
                Deliverable ID from the task's `deliverables` list (for example
                `f_01`, `f_02`).
              example: f_01
  responses:
    Unauthorized:
      description: Missing or invalid API key. Send your key in the `X-API-Key` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_or_invalid:
              summary: Missing or invalid API key
              value:
                error: Unauthorized
                message: API key is missing or invalid
            invalid_key:
              summary: Invalid API key (endpoint response)
              value:
                success: false
                error: Invalid API key
    Forbidden:
      description: >-
        The API key is disabled, revoked or lacks permission for this operation.
        A request over the rate limit returns `429`, not `403`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              summary: Key disabled or revoked
              value:
                error: Forbidden
                message: Access denied - API key is invalid, disabled, or revoked
            permission:
              summary: Key lacks permission
              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).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.