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

# Respond to HITL Checkpoint

> Reference for responding to a human-in-the-loop checkpoint via POST /v1/deepresearch/tasks/\{id\}/respond.

Resume a task waiting at a human-review checkpoint. Read its current `interaction` from [Get status](https://docs.valyu.ai/api-reference/endpoint/deepresearch-status.md), then submit that interaction's ID and the response shape required for its type.

The task must be in `awaiting_input` or `paused` state; otherwise the request returns `409`. A `409` with `Task is no longer paused.` means the task was cancelled while it was being resumed. Do not reuse an interaction ID from an earlier checkpoint.

A `paused` task needs enough balance to cover its mode price when it resumes. If the balance no longer covers it, the task ends as `failed` and is not charged. See [human-in-the-loop research](https://docs.valyu.ai/guides/deepresearch-hitl.md) for the interaction flow.


## OpenAPI

````yaml POST /v1/deepresearch/tasks/{id}/respond
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}/respond:
    post:
      tags:
        - DeepResearch
      summary: Respond to a HITL checkpoint
      description: >-
        Respond to a human-in-the-loop checkpoint. The task must be in
        `awaiting_input` or `paused` status. Pass the `interaction_id` from the
        task's `interaction` field along with the response data matching the
        checkpoint type.


        A `paused` task needs enough balance to cover its mode price when it
        resumes. If the balance no longer covers it, the task ends as `failed`
        and is not charged.
      operationId: respondToDeepResearch
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: DeepResearch task ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - interaction_id
                - response
              properties:
                interaction_id:
                  type: string
                  description: The interaction_id from the task's interaction field.
                response:
                  description: >-
                    Response data - shape depends on the checkpoint type
                    (`interaction.type`).
                  anyOf:
                    - $ref: '#/components/schemas/HitlPlanningQuestionsResponse'
                    - $ref: '#/components/schemas/HitlPlanReviewResponse'
                    - $ref: '#/components/schemas/HitlSourceReviewResponse'
                    - $ref: '#/components/schemas/HitlOutlineReviewResponse'
            examples:
              Planning Questions:
                summary: Answer planning questions
                value:
                  interaction_id: int_abc123
                  response:
                    answers:
                      - question: What geographic regions?
                        answer: North America and EU
                      - question: Specific competitors?
                        answer: Tesla, BYD, Rivian
              Plan Review:
                summary: Approve research plan
                value:
                  interaction_id: int_abc123
                  response:
                    approved: true
              Source Review:
                summary: Filter sources by domain
                value:
                  interaction_id: int_abc123
                  response:
                    included_domains:
                      - sec.gov
                      - plos.org
                    excluded_domains:
                      - example.com
      responses:
        '200':
          description: Response accepted. Task resumes processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    description: >-
                      `running` if container was still alive, `queued` if task
                      was re-enqueued from paused state.
                    enum:
                      - running
                      - queued
                    example: running
                  deepresearch_id:
                    type: string
                    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '400':
          description: Validation error in response data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: response.answers must be an array
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The task is not in `awaiting_input` or `paused` status, the
            `interaction_id` does not match, or the task was cancelled while it
            was being resumed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Cannot respond to task with status: running. Task must be
                      in 'awaiting_input' or 'paused' status.
              examples:
                wrong_status:
                  summary: Task not waiting for input
                  value:
                    error: >-
                      Cannot respond to task with status: running. Task must be
                      in 'awaiting_input' or 'paused' status.
                no_longer_paused:
                  summary: Task cancelled during resume
                  value:
                    error: Task is no longer paused.
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    HitlPlanningQuestionsResponse:
      type: object
      title: Planning Questions Response
      description: >-
        Response shape for the `planning_questions` checkpoint. Provide answers
        to each clarifying question.
      required:
        - answers
      properties:
        answers:
          type: array
          description: Answers to each question.
          items:
            type: object
            required:
              - question
              - answer
            properties:
              question:
                type: string
                description: The original question text.
                example: What geographic regions should the research focus on?
              answer:
                type: string
                description: Your answer.
                example: North America and EU
    HitlPlanReviewResponse:
      type: object
      title: Plan Review Response
      description: >-
        Response shape for the `plan_review` checkpoint. Approve the plan or
        request modifications.
      required:
        - approved
      properties:
        approved:
          type: boolean
          description: Whether to approve the plan.
          example: true
        modifications:
          type: string
          description: >-
            Free-text guidance for the model. Only used when `approved` is
            `false`.
          example: Focus more on battery supply chains and less on historical context
    HitlSourceReviewResponse:
      type: object
      title: Source Review Response
      description: >-
        Response shape for the `source_review` checkpoint. Specify which domains
        to include or exclude. Domains not listed in either array fall back to
        the AI recommendation.
      required:
        - included_domains
        - excluded_domains
      properties:
        included_domains:
          type: array
          description: >-
            Domains to include. Pass empty `[]` to accept all AI
            recommendations.
          items:
            type: string
          example:
            - sec.gov
            - plos.org
        excluded_domains:
          type: array
          description: Domains to exclude. Pass empty `[]` to not exclude any.
          items:
            type: string
          example:
            - example.com
    HitlOutlineReviewResponse:
      type: object
      title: Outline Review Response
      description: >-
        Response shape for the `outline_review` checkpoint. Approve the outline,
        describe changes in text, send an edited `write_plan`, or combine these.
        Send `approved`, `write_plan`, or both. If the edited `write_plan` is
        not valid (for example, a section has no evidence), the task uses the
        proposed outline. The report uses the approved sections as its main
        headings, in the same order.
      properties:
        approved:
          type: boolean
          description: >-
            Whether to approve the outline as shown. Required unless you send
            `write_plan`.
          example: true
        modifications:
          type: string
          description: >-
            Written changes to the outline. The report follows the outline and
            then applies these changes. Maximum 8,000 characters.
          maxLength: 8000
          example: >-
            Add a section on regulatory risks between Market Analysis and
            Competitive Landscape
        write_plan:
          $ref: '#/components/schemas/HitlWritePlan'
    HitlWritePlan:
      type: object
      title: Write Plan
      description: >-
        The outline as an object that you can edit and send back in the
        `write_plan` field of the `outline_review` response. Copy the object
        from the review data and change it. The `nodes` values in each section
        are identifiers that you must copy from the review data.
      required:
        - sections
        - exclude
        - open_questions
      properties:
        sections:
          type: array
          description: The sections of the report, in order. At least one section.
          minItems: 1
          items:
            type: object
            required:
              - title
              - nodes
              - weight
              - depth
            properties:
              title:
                type: string
                description: The section heading.
              nodes:
                type: array
                description: >-
                  The research topics that supply evidence for the section. At
                  least one. Copy the values from the review data.
                minItems: 1
                items:
                  type: string
                example:
                  - n_00
              weight:
                type: integer
                description: Relative importance of the section, from 1 to 5.
                minimum: 1
                maximum: 5
              depth:
                type: string
                description: How deep the section goes.
                enum:
                  - brief
                  - standard
                  - deep
              description:
                type: string
                description: >-
                  One sentence on what the section covers. Maximum 400
                  characters.
                minLength: 1
                maxLength: 400
              estimated_length:
                type: string
                description: The planned length of the section.
                enum:
                  - short
                  - medium
                  - long
              must_cite:
                type: array
                description: >-
                  Documents that the section must cite. Copy the identifiers
                  from the review data.
                items:
                  type: string
        exclude:
          type: array
          description: >-
            Documents to leave out of the report, with the reason. Send `[]` to
            exclude none.
          items:
            type: object
            required:
              - id
              - reason
            properties:
              id:
                type: string
                description: The document identifier.
              reason:
                type: string
                description: Why the document is left out.
        open_questions:
          type: array
          description: >-
            Questions that the research could not settle. The report states
            them. Send `[]` if there are none.
          items:
            type: string
    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.
  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
    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.