DeepResearch human-in-the-loop checkpoints

Let a user approve the research plan, clarify scope or choose which sources to include before the task continues. These optional checkpoints are configured through hitl (human-in-the-loop). Enable only the decisions your user needs to make; an ordinary research task needs none.

HITL is for individual tasks only. It is not available for batch requests.

Checkpoints

Checkpoint	Phase	What happens
`planning_questions`	Pre-research	Agent asks clarifying questions before researching
`plan_review`	Pre-research	User reviews the research plan
`source_review`	Post-research	User filters sources by domain
`outline_review`	Post-research	User reviews the report outline

Each pause sets the task status to awaiting_input. If you don’t respond within 5 minutes it becomes paused (state saved) - you can still respond later to resume; the task re-enqueues at highest priority with a brief cold-start delay. If you resume more than 24 hours after the pause, the task needs enough available balance for its mode price when it restarts; otherwise it fails with an Insufficient credits - ... error and is not charged.

Quick start

Pass an on_interaction callback to wait() to handle checkpoints. The example below shows the response shapes and automatically approves reviews. For human review, display the checkpoint in your application and submit the user’s decision through the respond endpoint.

from valyu import Valyu

client = Valyu()

task = client.deepresearch.create(
    query="Analyze the competitive landscape of AI chip manufacturers",
    mode="heavy",
    hitl={"plan_review": True, "source_review": True},
)

def handle_interaction(interaction):
    if interaction.type in ("plan_review", "outline_review"):
        return {"approved": True}
    if interaction.type == "source_review":
        return {"included_domains": [], "excluded_domains": []}
    if interaction.type == "planning_questions":
        return {
            "answers": [
                {"question": q["question"], "answer": "Use your best judgment"}
                for q in interaction.data["questions"]
            ]
        }
    return None

result = client.deepresearch.wait(
    task.deepresearch_id,
    on_interaction=handle_interaction,
)
print(result.output)

import Valyu from "valyu-js";

const client = new Valyu();

const task = await client.deepresearch.create({
  query: "Analyze the competitive landscape of AI chip manufacturers",
  mode: "heavy",
  hitl: { planReview: true, sourceReview: true },
});

const result = await client.deepresearch.wait(task.deepresearch_id!, {
  onInteraction: async (interaction) => {
    if (interaction.type === "plan_review" || interaction.type === "outline_review") {
      return { approved: true };
    }
    if (interaction.type === "source_review") {
      return { included_domains: [], excluded_domains: [] };
    }
    if (interaction.type === "planning_questions") {
      return {
        answers: interaction.data.questions.map((q: any) => ({
          question: q.question,
          answer: "Use your best judgment",
        })),
      };
    }
    return null;
  },
});

console.log(result.output);

# 1. Create task with HITL
curl -X POST https://api.valyu.ai/v1/deepresearch/tasks \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VALYU_API_KEY" \
  -d '{
    "query": "Analyze the competitive landscape of AI chip manufacturers",
    "mode": "heavy",
    "hitl": { "planning_questions": true, "plan_review": true }
  }'

# 2. Poll status until "awaiting_input"
curl https://api.valyu.ai/v1/deepresearch/tasks/{id}/status \
  -H "x-api-key: $VALYU_API_KEY"

# 3. Respond to the checkpoint
curl -X POST https://api.valyu.ai/v1/deepresearch/tasks/{id}/respond \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VALYU_API_KEY" \
  -d '{
    "interaction_id": "int_abc123",
    "response": {
      "answers": [{"question": "What geographic regions?", "answer": "North America and EU"}]
    }
  }'

Both SDKs also ship type-safe helpers: respond_planning_questions() / respondPlanningQuestions(), approve_plan() / approvePlan(), respond_source_review() / respondSourceReview(), and approve_outline() / approveOutline(). See the Python and TypeScript SDK references.

Where checkpoints fire

Query analysis

The agent analyzes the query.

planning_questions

Pause: clarifying questions before research starts. You answer to set scope.

plan_review

Pause: review the research plan. Approve or request changes.

Research execution

The agent searches and reads sources.

source_review

Pause: review sources grouped by domain. Include or exclude domains.

outline_review

Pause: review the report outline. Approve or request structural changes.

Report writing

The agent writes the final report and the task completes.

Checkpoint response shapes

When status is awaiting_input, status.interaction.data holds the checkpoint payload and you reply with a matching response.

planning_questions

The agent asks questions; you answer them.

// interaction.data
{ "questions": [
  { "question": "What geographic regions should the research focus on?" },
  { "question": "Are there specific competitors you want analyzed?" }
] }

// response
{ "answers": [
  { "question": "What geographic regions?", "answer": "North America and EU" },
  { "question": "Specific competitors?", "answer": "Tesla, BYD, Rivian" }
] }

answers is required: an array of { question, answer } strings.

plan_review and outline_review

Both share the same response shape - approve, or reject with free-text guidance.

// approve
{ "approved": true }

// request modifications
{ "approved": false, "modifications": "Add a regulatory risks section" }

approved (boolean) is required; modifications (string) is optional free-text guidance for the model. interaction.data contains the plan / outline and section breakdown for you to display.

source_review

interaction.data lists sources grouped by domain with a source_count, avg_relevance_score, and an ai_recommendation of include or exclude. You reply with explicit include/exclude lists.

{
  "included_domains": ["sec.gov", "plos.org"],
  "excluded_domains": ["example.com"]
}

Both arrays are required but may be empty. Domains you don’t list fall back to the AI recommendation.

Manual polling and the respond endpoint

If you poll yourself instead of using wait(), watch for awaiting_input (or paused), then POST your response:

POST /v1/deepresearch/tasks/:id/respond
{ "interaction_id": "<must match status.interaction.interaction_id>", "response": { ... } }

Code	Meaning
`200`	Accepted - `{ "success": true, "status": "running" \| "queued" }`
`400`	Validation error (bad response shape)
`409`	Wrong status or `interaction_id` mismatch. Also `Task is no longer paused.` if the task was cancelled while you were resuming it

Status values and interaction fields

Status	Meaning
`awaiting_input`	Checkpoint active, container held, fast resume on response
`paused`	Checkpoint timed out (5 min), state saved, respond later to resume
`running`	Research or writing in progress
`queued`	Re-enqueued after responding to a paused task

When HITL is enabled, the status response also carries hitl_config (mirrors the request), interaction (present while awaiting_input/paused), and hitl_history (one entry per completed checkpoint with interaction_id, type, created_at, responded_at, auto_continued, and response).

Best practices

Poll faster around checkpoints - 2-3s when expecting input, 5-10s during research phases.
Handle both awaiting_input and paused - the UX is identical, only resume speed differs.
Enable selectively - each checkpoint adds latency equal to the user’s response time.
Review decisions that matter - enable checkpoints where user input can change scope, sources or report structure. Choose the research mode separately.

Next steps

Use the application guide to persist task IDs and display waiting states. For every request and response field, see the Python or TypeScript reference.

Start here

APIs

Finance workflows

Sciences workflows

Build and connect

Comparisons

Review research before it continues

Checkpoints

Quick start

Where checkpoints fire

Checkpoint response shapes

Manual polling and the respond endpoint

Best practices

Next steps

​Checkpoints

​Quick start

​Where checkpoints fire

​Checkpoint response shapes

​Manual polling and the respond endpoint

​Best practices

​Next steps

Checkpoints

Quick start

Where checkpoints fire

Checkpoint response shapes

Manual polling and the respond endpoint

Best practices

Next steps