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/researchStart 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. Tier cap applies: Free 0, Starter 10, Growth 20, Pro 30, Scale 100. Default: 10. |
topic | string | No | Focus area hint: "general", "news", or "finance". Adjusts search strategy. |
deep | boolean | No | Enable deep mode. Uses Opus synthesis, more sources, longer reports. Consumes 10 of your monthly research runs 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 |
| Cost | 1 research run | 10 research runs |
Warning
Research is metered separately from the unified credit pool. Deep mode consumes 10 of your monthly research runs per job, normal mode consumes 1. The credit pool is untouched either way.
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/historyList 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
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.