Research

Deep research with AI synthesis -- multi-source analysis with citations. Searches the web, scrapes sources, extracts findings, and synthesizes everything into a comprehensive report.

POST/v1/research

Start an async research job. Returns a job ID to poll for results.

Note

Research is async. POST creates the job and returns immediately with an ID. Poll GET /v1/research/{id} until status is "completed" or "failed".

Request body

json

{
  "query": "Impact of AI on pharmaceutical drug discovery",
  "deep": false,
  "max_iterations": 3,
  "max_sources": 10,
  "topic": "general"
}

Parameters

Field	Type	Required	Description
`query`	`string`	Yes	The research question or topic to investigate.
`max_iterations`	`number`	No	Research depth -- how many search/analyze cycles to run. Default: 3.
`max_sources`	`number`	No	Maximum pages to analyze. Default: 10.
`topic`	`string`	No	Focus area hint: "general", "news", or "finance". Adjusts search strategy.
`deep`	`boolean`	No	Enable deep mode -- uses Opus synthesis, 50 sources, 15k+ word reports. Costs 10 credits instead of 1. Default: false.

Normal vs Deep mode

	Normal	Deep
Synthesis model	Sonnet 4.6	Opus 4.6
Default sources	10	50
Report length	5-8k words	15k+ words
Typical time	3-6 minutes	8-12 minutes
Credit cost	1 research credit	10 research credits

Warning

Deep mode costs 10 research credits per job. Normal mode costs 1 credit.

Create response

Returned immediately when the job is created.

json

{
  "id": "res_19d0661c943",
  "status": "processing"
}

Poll for results

GET/v1/research/{id}

Get the status and results of a research job.

Poll every 2-5 seconds. When status is "completed", the full report and findings are included.

json

{
  "id": "res_19d0661c943",
  "status": "completed",
  "query": "Impact of AI on pharmaceutical drug discovery",
  "report": "# AI in Drug Discovery\n\n## Executive Summary\n...",
  "sources": [
    { "url": "https://nature.com/...", "title": "AI-driven drug discovery", "words": 3200 }
  ],
  "findings": [
    { "fact": "AlphaFold has predicted structures for 200M+ proteins", "source_url": "https://...", "confidence": "high" }
  ],
  "iterations": 3,
  "elapsed_ms": 349000
}

Research history

GET/v1/research/history

List past research results for the authenticated user.

json

// Query params: ?limit=20&offset=0
{
  "results": [
    {
      "id": "res_19d0661c943",
      "query": "Impact of AI on pharmaceutical drug discovery",
      "status": "completed",
      "sources": 10,
      "findings": 89,
      "iterations": 3,
      "elapsed_ms": 349000,
      "created_at": "2026-03-19T13:56:05Z"
    }
  ]
}

SDK examples

cURL

bash

# Start research job
curl -X POST https://api.webclaw.io/v1/research \
  -H "Authorization: Bearer wc_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "Impact of AI on drug discovery", "deep": true}'

# Poll for results
curl https://api.webclaw.io/v1/research/res_19d0661c943 \
  -H "Authorization: Bearer wc_..."

TypeScript

typescript

import Webclaw from "@webclaw/sdk";

const client = new Webclaw({ apiKey: "wc_..." });

// Normal research
const job = await client.research("Impact of AI on drug discovery");
console.log(job.report);

// Deep research
const deep = await client.research("Impact of AI on drug discovery", { deep: true });
console.log(`${deep.report.split(" ").length} words`);

Python

python

from webclaw import Webclaw

client = Webclaw(api_key="wc_...")

# Normal research
job = client.research("Impact of AI on drug discovery")
print(job.report)

# Deep research
job = client.research("Impact of AI on drug discovery", deep=True)
print(f"{len(job.report.split())} words, {job.sources_count} sources")

Go

import webclaw "github.com/0xMassi/webclaw-go"

client := webclaw.NewClient("wc_...")

// Start research job
job, err := client.Research(ctx, webclaw.ResearchRequest{
    Query:         "Impact of AI on drug discovery",
    Deep:          true,
    MaxIterations: 3,
    MaxSources:    10,
})
if err != nil {
    log.Fatal(err)
}

// Poll until complete (checks every 5s, 10min timeout)
result, err := client.WaitForResearch(ctx, job.ID, 5*time.Second, 10*time.Minute)
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.Report)
fmt.Printf("%d sources, %d findings\n", len(result.Sources), len(result.Findings))

Note

The report is returned as markdown with inline citations like [1], [2] that reference the sources array. Findings include a confidence rating (high, medium, low) based on source authority.