> ## Documentation Index > Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt > Use this file to discover all available pages before exploring further. # Runs # `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` ```python theme={null} progress_snapshot(self) -> Any ``` Deprecated alias for `snapshots.get(detail=...)`. #### `full_progress` ```python theme={null} full_progress(self) -> RunObservabilitySnapshot ``` Return the full observability snapshot (deprecated path — use `snapshots.get(detail='full')`). #### `stream_transcript` ```python theme={null} stream_transcript(self) -> Iterator[dict[str, Any]] ``` Stream transcript event pages for the run. #### `work_product_content` ```python theme={null} work_product_content(self, work_product_id: str) -> str | bytes ``` Download work product bytes or text by id. #### `download_workspace_archive` ```python theme={null} download_workspace_archive(self, destination: str) -> dict[str, Any] ``` Deprecated alias for `workspace.download`. #### `list_artifacts` ```python theme={null} list_artifacts(self) -> List[dict[str, Any]] ``` Deprecated alias for `artifacts.list`. ### `ResearchRunsAPI` Public Research run methods (alpha must-have). **Methods:** #### `runbook_presets` ```python theme={null} runbook_presets(self) -> tuple[ResearchRunbookPreset, ...] ``` Return supported runbook presets for `runs.create`. #### `check_preflight` ```python theme={null} 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` ```python theme={null} launch_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Deprecated alias for `check_preflight`. #### `create` ```python theme={null} 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` ```python theme={null} start(self, objective: str, **kwargs: Any) -> ResearchRunHandle ``` Start a run with a primary objective message (deprecated — use `create`). #### `launch` ```python theme={null} launch(self, objective: str, **kwargs: Any) -> ResearchRunHandle ``` Deprecated alias for `create` with a required objective. #### `trigger` ```python theme={null} trigger(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Compatibility alias for existing ReportBench drivers. #### `start_run` ```python theme={null} start_run(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Deprecated alias for configured-run launch (prefer `create`). #### `get` ```python theme={null} 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` ```python theme={null} open(self, *args: str) -> ResearchRunHandle ``` Open a run session (alias for `get`). #### `state` ```python theme={null} state(self, run_id: str) -> ResearchRun ``` Return the public run model without opening a full session handle. #### `public_state` ```python theme={null} public_state(self, run_id: str) -> ResearchRun ``` Return the public run model without opening a full session handle. #### `list` ```python theme={null} list(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]] ``` List runs for a project (newest first). #### `list_active` ```python theme={null} list_active(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]] ``` Return active runs for a project (eval-compat name). #### `wait` ```python theme={null} 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` ```python theme={null} transcript(self, run_id: str) -> dict[str, Any] ``` Fetch a transcript page for a run (prefer `handle.transcript.get`). #### `stream_events` ```python theme={null} stream_events(self, run_id: str) -> Iterator[RunRuntimeStreamEvent] ``` Stream runtime events for a run (prefer `handle.events.stream`). #### `resource_limits` ```python theme={null} resource_limits(self, run_id: str) -> SmrResourceLimits ``` Return configured resource limits for the run. #### `progress_toward_resource_limits` ```python theme={null} progress_toward_resource_limits(self, run_id: str) -> SmrResourceLimitProgress ``` Return progress toward resource limits for the run. #### `stop` ```python theme={null} stop(self, run_id: str) -> ManagedResearchRunControlAck ``` Request graceful stop for a run. #### `pause` ```python theme={null} pause(self, run_id: str) -> ManagedResearchRunControlAck ``` Pause a running run. #### `resume` ```python theme={null} resume(self, run_id: str) -> ManagedResearchRunControlAck ``` Resume a paused run. #### `results` ```python theme={null} results(self, project_id: str, run_id: str) -> dict[str, Any] ``` Return final run results when execution completes. #### `logs` ```python theme={null} logs(self, project_id: str, run_id: str) -> dict[str, Any] ``` List structured log records for a run. #### `logs_page` ```python theme={null} 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` ```python theme={null} execution(self, project_id: str, run_id: str, **kwargs: Any) -> Any ``` Return orchestrator execution metadata for a run. #### `orchestrator` ```python theme={null} orchestrator(self, project_id: str, run_id: str) -> dict[str, Any] ``` Return orchestrator state for a run (actors, phases, checkpoints).