# Web research

> Research a question across many web sources and get a cited report or structured data, as a long-running job.

`web_research` researches a question across many web sources and returns a written report with citations, or data in the shape of `output_schema`. It takes from under a minute to several minutes; use [`web_answer`](https://clonvo.com/docs/web-answer.md) for a quick fact.

Call it with `POST /v1/tools/web_research`, or as `web_research` over [MCP](https://clonvo.com/docs/mcp.md). It runs as a [job](https://clonvo.com/docs/jobs.md): you get a job id, and the report when it finishes.

## Arguments

-   `query` string Required
    
    The question or research brief.
    
-   `depth` string
    
    "standard" (default) or "deep": deep reads more sources, takes longer and costs more.
    
    One of `standard` `deep`
    
-   `output_schema` object
    
    A JSON Schema with "type": "object" for structured output instead of a written report.
    

## Example

```bash
curl https://api.clonvo.com/v1/tools/web_research \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "query": "Which open source vector databases support hybrid search?" } }'
```

The call answers `202` with a running job:

```json
{
  "id": "gen-01M6B4Q8R2T4V6X8Z0B2D4F6H8",
  "object": "tool.job",
  "tool": "web_research",
  "status": "running",
  "provider": "clonvo",
  "created_at": "2026-11-09T12:00:00.000Z",
  "completed_at": null,
  "poll_after_ms": 10000
}
```

Check it with `GET /v1/tools/jobs/{id}`, waiting about `poll_after_ms` between checks:

```bash
curl https://api.clonvo.com/v1/tools/jobs/gen-01M6B4Q8R2T4V6X8Z0B2D4F6H8 \
  -H "Authorization: Bearer $CLONVO_API_KEY"
```

```json
{
  "id": "gen-01M6B4Q8R2T4V6X8Z0B2D4F6H8",
  "object": "tool.job",
  "tool": "web_research",
  "status": "completed",
  "provider": "clonvo",
  "created_at": "2026-11-09T12:00:00.000Z",
  "completed_at": "2026-11-09T12:01:52.000Z",
  "result": {
    "query": "Which open source vector databases support hybrid search?",
    "answer": "## Summary\n\nWeaviate, Qdrant and Milvus combine keyword (BM25 or sparse vector) search with dense vector search in one query…",
    "citations": [
      { "title": "Hybrid search | Weaviate Documentation", "url": "https://docs.weaviate.io/weaviate/search/hybrid" },
      { "title": "Hybrid Queries - Qdrant", "url": "https://qdrant.tech/documentation/concepts/hybrid-queries/" }
    ]
  },
  "usage": { "cost": 0.01, "charged": 0.0102, "is_byok": false }
}
```

## Result

Once the job is `completed`, its `result` has:

| Field | Description |
| --- | --- |
| `query` | The question or brief you sent. |
| `answer` | The report, as markdown. |
| `data` | With `output_schema`: the data in that shape. |
| `citations[]` | The sources, each with `title` and `url`, and `snippet` and `published_at` when the provider gives them. |
| `notes` | Present when the provider handled an argument differently. |

The job’s other fields are described in [Jobs](https://clonvo.com/docs/jobs.md#the-job-object).

## Notes

-   `depth: "deep"` reads more sources, takes longer and costs more than `standard`.
-   On Clonvo credits, Clonvo holds the most the research can cost at the `depth` you asked for before it starts; see [Research and browser tasks on credits](https://clonvo.com/docs/tool-billing.md#research-and-browser-tasks-on-credits).
-   Some providers can’t stop a research run once it has started, so cancelling it may not stop the charge; see [Jobs](https://clonvo.com/docs/jobs.md#cancel-a-job).
-   A research brief is free text, like a prompt, so it’s never stored as a [web tool query](https://clonvo.com/docs/privacy.md#web-tool-queries).