parallel-deep-research

Deep Research

Research topic: $ARGUMENTS

Requires parallel-cli ≥ 0.3.0 for text output and context chaining. If a documented command or option is missing, check parallel-cli --version and that command's --help. API, authentication and input errors are not evidence of an older CLI.

When to use (vs parallel-web-search)

ONLY use this skill when the user explicitly requests deep/exhaustive research. It can take several minutes and costs more than a quick search, depending on the processor and task. For normal "research X" requests, quick lookups, or fact-checking, use parallel-web-search instead.

Step 1: Start the research

Choose a descriptive output base in a persistent directory (e.g., reports/ai-chip-market-2026). Include the returned run ID to make it unique, then use this base in step 2 as -o "$FILENAME". Check for existing .json and .md files before saving.

parallel-cli research run "$ARGUMENTS" --processor pro-fast --text --no-wait --json

The --text flag tells the API to return a markdown report (with inline citations) when the task completes, instead of the default structured JSON. Use it for narrative/report-style requests, which is what most users want from "deep research." Drop --text if the user explicitly wants structured JSON output.

Optional with --text: pass --text-description "Keep under 1500 words, focus on M&A activity" to steer length, format, or focus.

If this is a follow-up and you have a prior Task's returned interaction_id, add context chaining. An enrichment taskgroup_id and a Search/Extract session_id are not Task interaction IDs. Async enrichment does not return a new interaction ID; retain the prior Task ID instead. Context chaining is unavailable for Zero Data Retention (ZDR) accounts, so omit it there and provide the needed context explicitly.

parallel-cli research run "$ARGUMENTS" --processor lite-fast --text --no-wait --json --previous-interaction-id "$INTERACTION_ID"

This reuses the prior Task's context. A lighter processor (lite-fast or base-fast) can suit a focused follow-up; choose based on the new question's depth rather than assuming all follow-ups are simple.

Always use --no-wait to separate creation from bounded polling. Save the returned IDs immediately. If creation is interrupted or its response is lost, do not submit a replacement until you have checked whether the first task was created.

Use pro-fast by default for exploratory research. Run parallel-cli research processors for the installed CLI's processor list and latency estimates; these are not deadlines. Choose ultra tiers only when explicitly requested and within the user's approved budget. Check current pricing rather than quoting fixed cost multipliers.

Fast variants prioritize speed and may use less fresh indexed data. Standard variants may suit freshness-sensitive work, but neither choice guarantees that every source was fetched live. State the relevant date or freshness requirement in the research prompt and check the returned evidence.

Parse the JSON output to save run_id, interaction_id, and result_url. Immediately tell the user:

• Deep research has been kicked off
• The estimated latency for the selected processor, if available
• The monitoring URL where they can track progress

The task runs server-side; polling can resume later using the saved run_id.

Step 2: Poll for results

parallel-cli research poll "$RUN_ID" -o "$FILENAME" --timeout 60

Important:

• Keep each poll bounded; --timeout 60 allows progress updates between waits.
• Avoid --json when polling a large report. The -o flag saves the full result to files.
• With -o "$FILENAME":
  • $FILENAME.json is always written (metadata + basis)
  • $FILENAME.md is written only for returned text output, normally requested with --text; auto-schema results can remain JSON-only.
  • For text, JSON references output.content_file relative to the saved JSON file instead of duplicating the report body.
• Share the executive summary if one was printed. Some successful outputs have no summary; do not invent one or treat its absence as failure.
• Existing output files are refused unless --force is explicit. Prefer a new base; use --force only when overwriting those files is intended.
• Read the actual printed paths. On a write error, the CLI may fall back to the system temp directory, and writes may be partial. Inspect both locations before retrying. Copy a final report from temporary storage to the intended persistent location before presenting it as saved durably.

If polling times out or is interrupted

Timeout exit 5 or interruption ends the local wait, not necessarily the server task. Check the saved task:

parallel-cli research status "$RUN_ID" --json

Resume the same poll only for a pending/running task; retrieve completed output and report failed/cancelled or action_required states accurately. The CLI's polling loop may not recognize action_required, so do not poll that state indefinitely. Never recreate the task merely because a local wait ended.

Response format

After step 1: Share the monitoring URL for tracking progress.

After step 2:

1. Share the executive summary if printed; otherwise say the result is saved and provide a brief summary only from inspected output when needed.
2. Tell the user the generated file paths:
   • Actual .md path, if a text report exists
   • Actual .json path with metadata and basis (and structured content for JSON output)
3. Share the interaction_id and tell the user they can ask follow-up questions that build on this research (e.g., "drill deeper into X" or "compare that to Y")

After completion, link the saved files rather than repeating the monitoring URL.

Avoid loading the whole report into context. Read only the relevant sections when answering a requested summary or follow-up, and cite the returned sources.

Remember the interaction_id: use it for a related research or enrichment follow-up when context chaining is supported by the account.

Setup

For authentication or API errors, inspect the returned message. A 403 can indicate permissions, account policy or billing; it does not prove low balance. Check parallel-cli auth --json and its authenticated boolean when relevant without exposing credentials. Only a billing-specific error warrants a balance check, and adding funds needs explicit confirmation. Reuse saved task IDs; do not automatically retry an ambiguous creation.