Write a research report
start_researchFits when the user wants a written report that answers a question from the live web, with the page behind each cited sentence, and has approved its price. Not for one fact or a quick answer, which the fast web search gives, or for a table of results. Starts a run that splits the question into parts, searches the live web, reads pages and writes a markdown report with numbered citations, or JSON that matches a given JSON Schema. A quick report takes about a minute, a deep one up to about fifteen. Returns the run's id, its status and its price at once. The report is charged once, at delivery, at its depth's price ($0.10 quick, $0.30 standard, $1.00 deep) from the account's balance; a failed or cancelled run is not charged. A depth priced above confirm_max_cents is refused, and the same idempotency_key returns the same run.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"question": "<question>",
"confirm_max_cents": "<confirm_max_cents>",
"idempotency_key": "<idempotency_key>"
},
"name": "start_research"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | quick, standard or deep: how far the run searches and reads, and its price. | standard |
| length | No | short, standard or long: the target length of the text, not of the research. | standard |
| language | No | The report's language. Without it, the language of the question. | |
| question | Yes | The question in plain words, in any language. | |
| output_schema | No | A JSON Schema for the answer. Without it, the report is markdown text. | |
| exclude_domains | No | Sites the run never reads. | |
| idempotency_key | Yes | A key that stays the same if this call is retried, so the run starts once. | |
| include_domains | No | Sites the run reads from, and no others. | |
| confirm_max_cents | Yes | The most the user approved for this report, in cents. A depth priced above it is refused and nothing runs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| depth | No | ||
| links | No | ||
| status | No | ||
| price_usd | No | ||
| created_at | No |