Synthesis

What it does

You ask a question; the agent plans, runs a few searches, and trims what does not belong — the kept results are the deliverable. Expect a few minutes per turn; progress shows live as it works.

Fields

• Question — what you want answered. Task / Context / Requirements — optional steering.
• Period — lookback in days (e.g. 7d); blank = all time. Absolute dates are refused — retrieval is a one-sided lookback, so from/to/start_date/end_date all return a 400 rather than being silently ignored.
• Turns — how many steps the agent takes (default 4, min 2 — turn 1 writes the plan; max 10). One turn is a single search pass; more turns let it react and dig deeper. Your ask is capped DOWN to the server's ceiling, never up.
• Effort — how long the agent reasons before it acts. It buys recall, not speed. Measured over 20 runs: lowering it cut articles kept by ~45% (≈21 vs ≈38) with no time saving — every tier landed between 382s and 457s. Reach for a lower tier to spend less, not to wait less; to wait less, lower Turns. Blank = the server default, and asking for the top tier is the same as blank (your ask is capped DOWN to the server's setting, never up).
• Stop — really cancels the run on the server (not just the watching). Everything gathered up to that moment is kept.

Effort, measured

The variance matters more than the tier. Probed twice with identical settings, this model produced 6,262 tokens in 52s once and 65,536 tokens in 330s the next — ten-fold, same input. A minority of turns cost ten times the median at any tier, and the higher tiers appear to run away more often. A run that takes far longer than these averages is usually that, not your settings.

Lower tiers exist in the underlying model API (medium, low, minimal, none) and are deliberately not offered: given a small budget a reasoning model spends it thinking and returns nothing. Anything outside the three is a 400, not a silent fallback — a typo cannot quietly cost you a run.

What comes back

• POST returns {"run_id":"…","status":"queued"} immediately — the run continues on the server whether or not you keep watching.
• Poll GET /v1/agent/runs/<run_id>. While running it carries status, turns_used, activity (a plain sentence: writing a research plan… / waiting for results… / reviewing results… / final review) and articles_held.
• Once status is done or failed, the SAME poll carries results — the kept articles. There is no second endpoint.
• done means finished. A run that spends its whole turn budget is also done: the deliverable is the results it kept, and spending the budget is the normal ending, not a failure.

Call it yourself

curl https://api.getsynthesis.ai/v1/agent/runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"question":"…","max_turns":4,"period":"7d","effort":"high"}'
# → {"run_id":"…","status":"queued"}                      ← the ONLY id there is
#
# fields:  question (required) · task · context · requirements   free text
#          period   "1d".."365d"        max_results 1-50   web_fetch true|false
#          max_turns 2-10               effort "high"|"xhigh"|"max"    ← agent runs only
#          from/to/start_date/end_date  → 400, use period
#
# poll:   GET  /v1/agent/runs/<run_id>                     progress while it works
#         the SAME poll carries {results:[…]} once status is done
# cancel: POST /v1/agent/runs/<run_id>/cancel              stops the run, keeps its work