Skip to main content

​
synth_ai.research.runs

Alpha client.research.runs — launch and lifecycle for Managed Research runs.

​
Classes

​
ResearchRunHandle

Run-scoped readouts and lifecycle (public hero session type). Prefer ResearchRunSession in type hints — RunHandle is not part of the public hero surface. Methods:

​
progress_snapshot 

progress_snapshot(self) -> Any
Deprecated alias for snapshots.get(detail=...).

​
full_progress 

full_progress(self) -> RunObservabilitySnapshot
Return the full observability snapshot (deprecated path — use snapshots.get(detail='full')).

​
stream_transcript 

stream_transcript(self) -> Iterator[dict[str, Any]]
Stream transcript event pages for the run.

​
work_product_content 

work_product_content(self, work_product_id: str) -> str | bytes
Download work product bytes or text by id.

​
download_workspace_archive 

download_workspace_archive(self, destination: str) -> dict[str, Any]
Deprecated alias for workspace.download.

​
list_artifacts 

list_artifacts(self) -> List[dict[str, Any]]
Deprecated alias for artifacts.list.

​
ResearchRunsAPI

Public Research run methods (alpha must-have). Methods:

​
runbook_presets 

runbook_presets(self) -> tuple[ResearchRunbookPreset, ...]
Return supported runbook presets for runs.create.

​
check_preflight 

check_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]
Validate a launch request before starting a run. Call after projects.setup.prepare to surface blockers (missing repo, secrets, budget caps) without creating a run record. Returns:
  • Preflight payload with allowed flag and structured denials.

​
launch_preflight 

launch_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]
Deprecated alias for check_preflight.

​
create 

create(self, project_id: str | None = None, **kwargs: Any) -> ResearchRunHandle | dict[str, Any]
Launch a Managed Research run. When objective is provided, starts a run with that primary message and returns a :class:ResearchRunHandle. Otherwise triggers a configured run and may return a wire dict (legacy drivers). Args:
  • project_id: Owning project id.
  • objective: Primary operator message for the run (preferred launch path).
Returns:
  • class:ResearchRunHandle when objective is set; otherwise a wire dict.

​
start 

start(self, objective: str, **kwargs: Any) -> ResearchRunHandle
Start a run with a primary objective message (deprecated — use create).

​
launch 

launch(self, objective: str, **kwargs: Any) -> ResearchRunHandle
Deprecated alias for create with a required objective.

​
trigger 

trigger(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]
Compatibility alias for existing ReportBench drivers.

​
start_run 

start_run(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any]
Deprecated alias for configured-run launch (prefer create).

​
get 

get(self, *args: str) -> ResearchRunHandle
Open a run-scoped session handle for readouts and lifecycle control. Accepts (project_id, run_id), (run_id,) when project is implied, or keyword forms. Prefer nested readouts on the returned handle: handle.usage.get(), handle.snapshots.get(), handle.transcript.get().

​
open 

open(self, *args: str) -> ResearchRunHandle
Open a run session (alias for get).

​
state 

state(self, run_id: str) -> ResearchRun
Return the public run model without opening a full session handle.

​
public_state 

public_state(self, run_id: str) -> ResearchRun
Return the public run model without opening a full session handle.

​
list 

list(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]]
List runs for a project (newest first).

​
list_active 

list_active(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]]
Return active runs for a project (eval-compat name).

​
wait 

wait(self, project_id: str | None = None, run_id: str | None = None) -> ResearchRun
Block until a run reaches a terminal state. Args:
  • timeout: Max seconds to wait (None waits indefinitely).
  • poll_interval: Seconds between status polls.
  • raise_if_failed: Raise when the run ends in a failed state.
Returns:
  • Final ResearchRun public state model.

​
transcript 

transcript(self, run_id: str) -> dict[str, Any]
Fetch a transcript page for a run (prefer handle.transcript.get).

​
stream_events 

stream_events(self, run_id: str) -> Iterator[RunRuntimeStreamEvent]
Stream runtime events for a run (prefer handle.events.stream).

​
resource_limits 

resource_limits(self, run_id: str) -> SmrResourceLimits
Return configured resource limits for the run.

​
progress_toward_resource_limits 

progress_toward_resource_limits(self, run_id: str) -> SmrResourceLimitProgress
Return progress toward resource limits for the run.

​
stop 

stop(self, run_id: str) -> ManagedResearchRunControlAck
Request graceful stop for a run.

​
pause 

pause(self, run_id: str) -> ManagedResearchRunControlAck
Pause a running run.

​
resume 

resume(self, run_id: str) -> ManagedResearchRunControlAck
Resume a paused run.

​
results 

results(self, project_id: str, run_id: str) -> dict[str, Any]
Return final run results when execution completes.

​
logs 

logs(self, project_id: str, run_id: str) -> dict[str, Any]
List structured log records for a run.

​
logs_page 

logs_page(self, project_id: str, run_id: str) -> SyncPage[dict[str, Any]]
Fetch a paginated page of run logs. Returns:
  • SyncPage with items, next_cursor, and has_more for
  • cursor-based iteration without hand-parsing wire payloads.

​
execution 

execution(self, project_id: str, run_id: str, **kwargs: Any) -> Any
Return orchestrator execution metadata for a run.

​
orchestrator 

orchestrator(self, project_id: str, run_id: str) -> dict[str, Any]
Return orchestrator state for a run (actors, phases, checkpoints).