Skip to main content
POST
Start an investigation

Headers

x-api-key
string | null

Body

application/json
lead_info
Lead Info · object
required

Who to investigate, e.g. {"name": "Jane Doe", "company": "Acme"}.

engine
enum<string>
default:xhigh

Research engine. GET /v1/atlas/access reports which ones this organization may run, and what each costs.

Available options:
xhigh,
scout
research_plan
string | null

Direction for this run. On a continue, what to look into next.

struct
Struct · object | null

Optional output schema. Atlas researches open-endedly into the workspace either way.

relentless
boolean
default:true

Research until the budget runs out (the Atlas default). Set false to let a run with struct stop once every field is answered, charging the turns it used (at least one unit).

max_credits
integer | null

How much research to buy, in credits (default: one unit of the engine price), up to 10 units. On xhigh every 250 credits buy 800 team turns, used in full unless the research stops yielding: 300 buys 960. Scout researches alone, and every 50 credits buy its 100 turns.

max_minutes
integer | null

The longest the run may research, in minutes of working time: waits to retry a model call or an attempt do not count. When it is reached the run writes up what it found and completes, charging the credits its turns used, rounded up to the next 50, instead of the whole budget. Writing up can take a few minutes past the limit. Default: no limit.

Required range: 10 <= x <= 1440
dispatch_id
string | null

Client-generated idempotency key. Reusing the same key for the same organization returns the existing run instead of starting and billing a duplicate, so a lost response is safe to retry.

Required string length: 8 - 128
name
string | null

Title for the investigation. Derived from lead_info when unset.

private
boolean
default:false

Visible only to you, not your team. Needs a signed-in user and a team that allows private runs.

Response

Successful Response

task_id
string
required

Poll with GET /job-status/{job_id}.

status
string
required
investigation
InvestigationReference · object
required

The investigation this run writes into. Readable through the routes below while the run is still going.