Research
Deep research with AI synthesis -- multi-source analysis with citations. Searches the web, scrapes sources, extracts findings, and synthesizes the findings into a report. Check its claims against the cited sources.
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",
"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: 5; values are clamped to 1–5. |
max_sources | number | No | Requested source limit: default 50, clamped to 1–100. Tier cap applies: Starter 10, Growth 20, Pro 30, Scale 100. |
topic | string | No | Focus area hint: "general", "news", or "finance". Adjusts search strategy. |
deep | boolean | No | Deprecated and ignored -- research always runs in deep mode. The field is still accepted so existing clients keep working. |
What a research run includes
Research always runs in deep mode -- there is no lighter tier to configure. The legacy deep flag is deprecated and ignored.
| Synthesis | Managed report synthesis |
| Sources | Limited by max_sources and your plan |
| Report length | Varies with the query and available evidence |
| Typical time | Varies with depth, sources, and provider availability |
| Cost | 1 research run (monthly allowance: Starter 3, Growth 10, Pro 20, Scale 60) |
Warning
Research is metered separately from the unified credit pool. A job reserves one run from your plan allowance. Failed jobs are refunded; the unified credit pool is untouched.
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.
Example response (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"}'
# 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_..." });
const job = await client.research({ query: "Impact of AI on drug discovery" });
if (job.status !== "completed" || !job.report) throw new Error("Research did not complete");
console.log(job.report);
console.log(`${job.report.split(" ").length} words`);Python
python
from webclaw import Webclaw
client = Webclaw(api_key="wc_...")
job = client.research("Impact of AI on drug discovery")
if job.status != "completed":
raise RuntimeError("Research did not complete")
print(job.report)
print(f"{len(job.report.split())} words, {len(job.sources)} 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",
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, &webclaw.ResearchPollOptions{
Interval: 5 * time.Second,
Timeout: 10 * time.Minute,
})
if err != nil {
log.Fatal(err)
}
if result.Status != "completed" {
log.Fatal("Research did not complete")
}
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) assigned by the model, not independently verified.