Start a research run (billed)
start_runStart a hosted deep-research run and return its id immediately. Billable, and the tier is the price: light ($9) answers one focused question or investigates a narrow topic; premier ($49, shown to people as "Deep") investigates a broader question across several research sections. Omitted, the tier is Light, the cheaper of the two — ask for premier by name when the question needs depth. No other tier can be started; asking for one is refused with 400 tier_not_offered. Track it with run_status and read run_result when done. Researching for a client or topic? Call list_projects first; if no project fits, call create_project, then pass its id as project_id on every run for that work. A filed run reuses the sources the project's earlier runs kept and tags every source it keeps project:<id> so search_notes({ project }) finds them; an unfiled run reuses nothing. To file a run you already started, use file_run. Pass idempotency_key to make retries safe. Pass levers.reader_expertise (beginner, intermediate or expert) to set who the report is written for, levers.purpose (decide, understand or brief_someone) to say what it is for, and levers.report_language (a language tag such as en, zh or ja) to set its language: they shape how the report is written and change nothing about the price, the sources or the run time. budget.fetch_usd_max, budget.sources_max, levers.inference_depth and levers.citation_style are deprecated: still accepted, but omit them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | Depth and price: `light` ($9) answers one focused question or investigates a narrow topic; `premier` ($49, shown to people as "Deep") investigates a broader question across several research sections. | light |
| query | Yes | The research question, in full, as you want it answered. | |
| budget | No | Deprecated spending caps: still accepted, omit them. | |
| levers | No | Optional settings for how the report is written. None of them change the price. | |
| clarify | No | auto (the default for agents) starts at once on stated assumptions; ask waits in status "clarifying" for answer_clarification; off skips clarification. | |
| profile | No | Trade-off between cost, speed and quality. | |
| project_id | No | File the run under this project (`proj_…` id from list_projects). | |
| idempotency_key | No | Any unique string. Retrying with the same key returns the first result instead of charging again. |