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

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

List edit records submitted for a DeepResearch task, including running, applied, declined, and failed edits.

Each item uses the same edit record shape returned by [Get edit](https://docs.valyu.ai/api-reference/endpoint/deepresearch-edit-get.md). Only the task owner can list edits for a task (`403` for shared or public viewers). See [Edit a finished report](https://docs.valyu.ai/guides/deepresearch-editing.md).


## OpenAPI

````yaml GET /v1/deepresearch/tasks/{id}/edits
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}/edits:
    get:
      tags:
        - DeepResearch
      summary: List edits for a task
      description: >-
        List edit records submitted for a DeepResearch task. Only the task owner
        can list edits.
      operationId: listDeepResearchEdits
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: List of edit records for the task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchEditListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    DeepResearchEditListResponse:
      type: object
      description: List of edits for a DeepResearch task.
      required:
        - deepresearch_id
        - edits
      properties:
        deepresearch_id:
          type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        edits:
          type: array
          description: Edit records for the task.
          items:
            $ref: '#/components/schemas/DeepResearchEditRecord'
    DeepResearchEditRecord:
      type: object
      description: Full record of a DeepResearch edit.
      required:
        - edit_id
        - deepresearch_id
        - status
        - target
        - base_version
        - created_at
      properties:
        edit_id:
          type: string
          description: Unique identifier for this edit.
          example: ed_01j9x4k2m8n7p3q5r6s8t0v2w4
        deepresearch_id:
          type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          enum:
            - running
            - applied
            - declined
            - failed
          description: Lifecycle status of the edit.
        target:
          $ref: '#/components/schemas/DeepResearchEditTarget'
        base_version:
          type: integer
          minimum: 1
          description: Version number the edit was applied against.
        version:
          type: integer
          minimum: 1
          nullable: true
          description: New version number created when `status` is `applied`.
        focus:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditFocus'
          description: Focus supplied in the edit request, if any.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the edit was created.
        retry_after_seconds:
          type: number
          nullable: true
          description: Suggested polling delay in seconds while `status` is `running`.
        summary:
          type: string
          nullable: true
          description: Short summary of the result.
        changes:
          type: array
          maxItems: 50
          description: >-
            The changed blocks of lines, in order, at most 50. Each block gives
            the 1-based line in the base version's output (the version the edit
            started from) where it begins, and the whole lines removed and
            added, at most 40 of each. `stats` counts the full edit even when
            this list is cut short.
          items:
            type: object
            required:
              - line
              - removed
              - added
            additionalProperties: false
            properties:
              line:
                type: integer
                minimum: 1
                description: >-
                  1-based line in the base version's output where the change
                  begins.
              removed:
                type: array
                maxItems: 40
                items:
                  type: string
                description: >-
                  Whole lines removed from the base version, in order. Empty for
                  a pure insertion.
              added:
                type: array
                maxItems: 40
                items:
                  type: string
                description: >-
                  Whole lines that replace them in the new version, in order.
                  Empty for a pure deletion.
        unapplied:
          type: array
          description: Parts of the instruction that could not be applied.
          items:
            oneOf:
              - type: string
              - type: object
                additionalProperties: true
        stats:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Metrics for the edit (such as replacement count and characters
            changed).
        warnings:
          type: array
          description: >-
            Warnings produced by the edit, such as `deliverables_stale` when a
            report edit runs on a task with deliverable files.
          items:
            $ref: '#/components/schemas/Warning'
        decline:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditDecline'
          description: Present when `status` is `declined`.
        error:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditError'
          description: Present when `status` is `failed`.
        pdf_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL to the re-rendered PDF for the new version when the task has a
            PDF.
    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
    DeepResearchEditFocus:
      type: object
      additionalProperties: false
      description: Optional pointer to a passage or section in the report.
      properties:
        start_char:
          type: integer
          minimum: 0
          description: >-
            Start UTF-16 offset into the `output` markdown of `base_version`.
            Must be given together with `end_char`, with `end_char >
            start_char`.
          example: 1840
        end_char:
          type: integer
          minimum: 1
          description: >-
            End UTF-16 offset into the `output` markdown of `base_version`. Must
            be given together with `start_char`, with `end_char > start_char`.
          example: 1965
        text:
          type: string
          maxLength: 20000
          description: >-
            Highlighted text to focus on. Offsets are trusted when `text`
            matches; otherwise `text` is searched for and narrowed by `prefix`,
            `suffix`, `section`, and the offset hint.
        prefix:
          type: string
          maxLength: 2000
          description: Text immediately before the passage to disambiguate matches.
        suffix:
          type: string
          maxLength: 2000
          description: Text immediately after the passage to disambiguate matches.
        section:
          type: string
          minLength: 1
          maxLength: 300
          description: Section heading. Sent alone, focuses that whole section.
          example: Executive Summary
        scope:
          type: string
          enum:
            - prefer
            - strict
          default: prefer
          description: >-
            `prefer` points the editor at the focused region (default). `strict`
            rejects changes outside the focus.
    Warning:
      type: object
      description: >-
        Something the request skipped or adjusted. A warning means the request
        succeeded. New `type` values may be added at any time, so handle unknown
        ones by showing `message`. See
        [Warnings](https://docs.valyu.ai/api-reference/warnings).
      required:
        - type
        - message
      properties:
        type:
          type: string
          description: >-
            Stable snake_case warning type, for example `datasets_not_in_plan`.
            New types may be added at any time.
          example: datasets_not_in_plan
        message:
          type: string
          description: >-
            Self-contained sentence, safe to show a user or for an agent to
            relay as-is.
          example: >-
            Your Pay-as-you-go plan doesn't include valyu/valyu-chemrxiv
            (Comfortably Pro, $99/mo), so it was skipped. Results come from your
            other sources. Comfortably Pro ($99/mo) includes it:
            https://platform.valyu.ai/user/account/billing?tab=plan
        detail:
          type: object
          nullable: true
          description: Optional type-specific structured fields, including any URLs.
          additionalProperties: true
          example:
            datasets:
              - id: valyu/valyu-chemrxiv
                required_plan: tier_2
            current_plan: tier_0
            required_plan:
              id: tier_2
              name: Comfortably Pro
              price: $99/mo
            upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
    DeepResearchEditDecline:
      type: object
      description: Reason an edit finished with status `declined`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - edit.rewrite_requested
            - edit.out_of_evidence
            - edit.contradictory
            - edit.unsafe_instruction
            - edit.not_applicable
            - edit.no_change
          description: Machine-readable decline code.
        message:
          type: string
          description: Human-readable explanation of why the edit was declined.
        suggestion:
          type: string
          nullable: true
          description: Suggested next step for the caller or user.
    DeepResearchEditError:
      type: object
      description: Failure details when an edit finishes with status `failed`.
      properties:
        code:
          type: string
          description: >-
            Stable error code, such as `edit.interrupted` when interrupted by a
            restart.
          example: edit.interrupted
        message:
          type: string
          description: Human-readable failure detail.
        retryable:
          type: boolean
          description: Whether submitting the edit again may succeed.
  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.