---
title: "Start research on a mission (managed or customer-directed)"
method: POST
path: "/preview/research"
tags: ["research"]
---

# Start research on a mission (managed or customer-directed)

`POST /preview/research`

## Request

- Base URL: `https://autoresearch.sfcompute.com`
- URL: `https://autoresearch.sfcompute.com/preview/research`
- Auth: HTTP bearer

Start research on a mission: attach a controller, a budget, a deadline, and pinned inputs (source, checks, benchmark) to a mission (created if new). planner "managed" (default) means the Autoresearch researcher designs and runs experiments against your objective, meters intelligence units at the tier you pick, and returns a confirmed result or an honest negative; planner "customer" means YOU submit research.plan/v1 plans (here, and later through steer_research) and the platform runs each experiment as a job from your uploaded source, evaluates it against your check set, and retains the evidence. Upload source first with create_context / finalize_context and pass the context id (autor research start --source . does this). The budget is a hard cap across intelligence units and experiment jobs, reserved before every dispatch; a fifth is held for confirming the selected result. Returns the mission url - hand it to the human - plus version and control_version, which steer_research needs. Work continues if you disconnect; get_research reads progress without calling a model.

## Query parameters

- `workspace` string

## Request body

- object
  - `benchmark` string, nullable: The benchmark command the managed researcher measures with ("./bench.sh --json results.json").
  - `budget_usd` number, double, required: The hard cap on everything this mission may spend: intelligence units, experiment jobs, builds. Enforced before dispatch.
  - `checks` unknown
  - `chip` string, nullable: The default chip for experiments: "h100" (default, GPU), "cpu-2" (2 reserved CPU cores, no GPU), or "cpu-8" (8 reserved CPU cores, no GPU). An experiment in a plan may name its own.
  - `chip_count` integer, nullable: Chips per execution on a GPU chip (1-8, default 1). A CPU shape is one reserved slot; the count does not apply to it.
  - `confirmation_reserve_usd` number, double, nullable: Held back from exploration for confirming a selected result. Default 20% of the budget.
  - `deadline_hours` number, double, nullable: Hours until the mission stops accepting work. Default 72.
  - `idempotency_key` string, nullable: Replay protection: the same key returns the first start's response.
  - `image` string, nullable: The default base image experiments build on (default: the catalog's).
  - `instructions` string[], nullable: Extra instructions for the managed researcher, one per entry.
  - `intelligence_tier` string, nullable: "i1" (default), "i2", or "i3": the intelligence tier the managed researcher runs at and the unit price it meters (see the rate card).
  - `name` string, required: The mission to research under (create-or-attach, like open_mission): lowercase letters, digits, '-' (1-63 chars), permanent, org-unique.
  - `objective` string, required: What the researcher is trying to achieve, in plain words. The managed researcher plans from this; a customer-directed mission records it beside the plan.
  - `plan` unknown
  - `planner` string, nullable: "managed" (default): Autoresearch's researcher selects experiments. "customer": you submit plans; the platform runs, evaluates, and retains them. Either can change later through steer_research.
  - `source_context` string, nullable: The uploaded source: a context id from create_context / finalize_context (`autor research start --source .` does this for you). Experiments run from its root. Optional for plans whose commands need only the base image.
  - `title` string, nullable: One-line mission title, when the mission is created here.

## Response `200`

The capability's JSON result.

- Result: The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.
  - `object` string: The resource type, when the result is one resource.

## Other responses

- `400`: Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.
- `401`: No bearer token, or one this API cannot verify. Code `unauthenticated`.
- `403`: Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.
- `404`: No such route. Code `not_found`; the body names the OpenAPI document.
- `422`: A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.
- `429`: Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.
- `500`: Our fault. Retry; if it persists, quote the request-id. Code `internal`.

---

[API](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api.md) · [All operations](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/revisions/f88dcb70ac6c?raw)