> ## 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.
# Run readouts
# `synth_ai.research.run_readouts`
Nested run readout namespaces on `ResearchRunHandle`.
## Classes
### `ResearchRunUsageActorsAPI`
Per-actor usage breakdown for a run.
**Methods:**
#### `get`
```python theme={null}
get(self) -> SmrRunActorUsage
```
Return token and cost usage grouped by runtime actor.
### `ResearchRunUsageCostAPI`
Run-level cost summary readouts.
**Methods:**
#### `get`
```python theme={null}
get(self) -> SmrRunCostSummary
```
Return aggregated cost fields for the run.
### `ResearchRunUsageLimitsAPI`
Org and run resource limit readouts.
**Methods:**
#### `get`
```python theme={null}
get(self) -> SmrResourceLimits
```
Return configured resource limits applicable to the run.
#### `progress`
```python theme={null}
progress(self) -> SmrResourceLimitProgress
```
Return progress toward resource limits (tokens, spend, concurrency).
### `ResearchRunUsageAPI`
Token, cost, and limit readouts for a run.
**Methods:**
#### `actors`
```python theme={null}
actors(self) -> ResearchRunUsageActorsAPI
```
Per-actor usage slice.
#### `cost`
```python theme={null}
cost(self) -> ResearchRunUsageCostAPI
```
Run cost summary slice.
#### `limits`
```python theme={null}
limits(self) -> ResearchRunUsageLimitsAPI
```
Resource limit and progress slice.
#### `get`
```python theme={null}
get(self) -> SmrRunUsage
```
Return canonical usage totals for the run.
### `ResearchRunProgressAPI`
High-level progress summary for dashboards and polling loops.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return coarse progress fields (phase, percent, status text).
### `ResearchRunSnapshotsAPI`
Observability snapshots (control vs full detail).
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return an observability snapshot for the run.
**Args:**
* `detail`: `"control"` for operator dashboard fields or `"full"` for
the expanded observability projection.
### `ResearchRunEventsObjectivesAPI`
Objective lifecycle events emitted during a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> dict[str, Any]
```
List objective events with optional cursor pagination.
**Args:**
* `limit`: Maximum events to return on this page.
* `cursor`: Opaque cursor from a prior response.
**Returns:**
* Event page payload including items and an optional next cursor.
### `ResearchRunEventsTasksAPI`
Task lifecycle events emitted during a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> dict[str, Any]
```
List task events with optional cursor pagination.
**Args:**
* `limit`: Maximum events to return on this page.
* `cursor`: Opaque cursor from a prior response.
**Returns:**
* Event page payload including items and an optional next cursor.
### `ResearchRunEventsAPI`
Structured and streaming runtime events for a run.
**Methods:**
#### `objectives`
```python theme={null}
objectives(self) -> ResearchRunEventsObjectivesAPI
```
Objective-scoped event list.
#### `tasks`
```python theme={null}
tasks(self) -> ResearchRunEventsTasksAPI
```
Task-scoped event list.
#### `stream`
```python theme={null}
stream(self) -> Iterator[RunRuntimeStreamEvent]
```
Stream runtime events over SSE.
**Args:**
* `transcript_cursor`: Resume streaming after this transcript cursor.
* `view`: Projection name (for example `"operator"`).
* `last_event_id`: Resume after this event id when reconnecting.
* `timeout`: Optional read timeout in seconds.
### `ResearchRunTasksAPI`
Task summaries attached to a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List task summaries for the run.
**Args:**
* `kind`: Optional task kind filter.
* `limit`: Maximum summaries to return.
### `ResearchRunMessageQueueMessagesAPI`
Outbound operator messages on the run message queue.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List queued messages, optionally scoped to a thread.
#### `send`
```python theme={null}
send(self, **kwargs: Any) -> dict[str, Any]
```
Publish a message to the run message queue.
**Args:**
* `body`: Message body text.
* `**kwargs`: Additional wire fields forwarded to the backend.
### `ResearchRunMessageQueueThreadsAPI`
Message queue threads for operator steering.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List message queue threads for the run.
### `ResearchRunMessageQueueInteractionsAPI`
Pending and completed message queue interactions.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List interactions, optionally filtered by status.
### `ResearchRunMessageQueueAPI`
Operator steering via threads, messages, and interactions.
**Methods:**
#### `messages`
```python theme={null}
messages(self) -> ResearchRunMessageQueueMessagesAPI
```
Outbound messages API.
#### `threads`
```python theme={null}
threads(self) -> ResearchRunMessageQueueThreadsAPI
```
Thread listing API.
#### `interactions`
```python theme={null}
interactions(self) -> ResearchRunMessageQueueInteractionsAPI
```
Interaction listing API.
### `ResearchRunRuntimeMessagesAPI`
Runtime messages visible to operators and viewers.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[dict[str, Any]]
```
List runtime messages for the run.
**Args:**
* `status`: Optional delivery or read status filter.
* `viewer_role`: Role used to project the message list.
* `viewer_target`: Optional target id or list of targets.
* `limit`: Maximum messages to return.
### `ResearchRunTranscriptAPI`
Transcript pages and cursor-based pagination for run events.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Fetch a transcript page (use `get_page` for `SyncPage` iteration).
#### `get_page`
```python theme={null}
get_page(self) -> SyncPage[dict[str, Any]]
```
Fetch a transcript page wrapped as `SyncPage` for iteration.
### `ResearchRunMilestonesAPI`
Run-scoped milestone readouts.
**Methods:**
#### `list_primary_parent`
```python theme={null}
list_primary_parent(self) -> List[dict[str, Any]]
```
List primary parent milestones linked to the run.
### `ResearchRunWorkProductsContentAPI`
Fetch work product payload bytes or text.
**Methods:**
#### `get`
```python theme={null}
get(self, work_product_id: str) -> str | bytes
```
Return work product content.
**Args:**
* `work_product_id`: Work product identifier from `list`.
* `as_text`: When `True`, decode as UTF-8 text; otherwise return bytes.
### `ResearchRunTrainedModelsAPI`
Trained model artifacts produced by a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List trained models registered for the run.
### `ResearchRunWorkProductsEvalPackagesAPI`
Container eval packages attached to run work products.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List eval packages exported from the run workspace.
### `ResearchRunWorkProductsAPI`
Work products and derived outputs from a run.
**Methods:**
#### `content`
```python theme={null}
content(self) -> ResearchRunWorkProductsContentAPI
```
Download work product bodies.
#### `eval_packages`
```python theme={null}
eval_packages(self) -> ResearchRunWorkProductsEvalPackagesAPI
```
List container eval packages.
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List work product metadata for the run.
### `ResearchRunArtifactsManifestAPI`
Artifact manifest for a run.
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return the artifact manifest describing available run outputs.
### `ResearchRunArtifactsContentAPI`
Download individual run artifacts.
**Methods:**
#### `get`
```python theme={null}
get(self, artifact_id: str) -> str | bytes
```
Return artifact content by id.
**Args:**
* `artifact_id`: Artifact identifier from `list` or the manifest.
* `as_text`: When `True`, decode as UTF-8 text; otherwise return bytes.
### `ResearchRunArtifactsAPI`
Run artifacts listing, manifest, and content download.
**Methods:**
#### `manifest`
```python theme={null}
manifest(self) -> ResearchRunArtifactsManifestAPI
```
Artifact manifest API.
#### `content`
```python theme={null}
content(self) -> ResearchRunArtifactsContentAPI
```
Artifact content download API.
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List artifacts for the run with optional type filter.
### `ResearchRunResultsAPI`
Final run results and outcome payload.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return the run results document when execution has finished.
### `ResearchRunLogsAPI`
Structured run logs for debugging and audit.
**Methods:**
#### `list`
```python theme={null}
list(self) -> dict[str, Any]
```
List log records with optional cursor pagination.
### `ResearchRunOrchestratorAPI`
Orchestrator state and routing metadata for a run.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return orchestrator readouts for the run.
### `ResearchRunWorkspaceAPI`
Run workspace archive download.
**Methods:**
#### `download`
```python theme={null}
download(self, destination: str) -> dict[str, Any]
```
Download the run workspace archive to a local path.
**Args:**
* `destination`: Local filesystem path for the archive.
* `timeout_seconds`: Optional download timeout.
### `ResearchRunCodeAPI`
Run code archive download.
**Methods:**
#### `download`
```python theme={null}
download(self, path: str) -> dict[str, Any]
```
Download run code to the given local path.
### `ResearchRunActorsAPI`
Runtime actor inventory for a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> dict[str, Any]
```
List actors participating in the run.
### `ResearchRunEvidenceAPI`
Operator evidence bundle for debugging run behavior.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return operator evidence with optional per-section limits.
### `ResearchRunAuthorityAPI`
Authority and permission readouts for operators.
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return authority readouts for the run.
**Args:**
* `include_runtime_authority`: Include live runtime authority fields when
available.
### `ResearchRunExecutionAPI`
Execution state and worker routing for a run.
**Methods:**
#### `get`
```python theme={null}
get(self, **kwargs: Any) -> Any
```
Return execution readouts for the run.
### `ResearchRunTickingAPI`
Run ticking / heartbeat controls for long-running workloads.
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return current ticking state for the run.
#### `set`
```python theme={null}
set(self, update: Any = None, **kwargs: Any) -> Any
```
Update ticking configuration for the run.
### `ResearchRunReadoutsMixin`
Lazy nested readout namespaces on :class:`ResearchRunHandle`.
Access via `handle.usage`, `handle.progress`, `handle.snapshots`,
`handle.transcript`, `handle.message_queue`, etc.
**Methods:**
#### `usage`
```python theme={null}
usage(self) -> ResearchRunUsageAPI
```
Usage, cost, and limit readouts.
#### `progress`
```python theme={null}
progress(self) -> ResearchRunProgressAPI
```
Coarse progress for polling UIs.
#### `snapshots`
```python theme={null}
snapshots(self) -> ResearchRunSnapshotsAPI
```
Observability snapshots (control or full).
#### `events`
```python theme={null}
events(self) -> ResearchRunEventsAPI
```
Structured and streaming runtime events.
#### `tasks`
```python theme={null}
tasks(self) -> ResearchRunTasksAPI
```
Task summaries for the run.
#### `message_queue`
```python theme={null}
message_queue(self) -> ResearchRunMessageQueueAPI
```
Operator message queue threads and outbound messages.
#### `messages`
```python theme={null}
messages(self) -> ResearchRunRuntimeMessagesAPI
```
Runtime messages visible to operators.
#### `transcript`
```python theme={null}
transcript(self) -> ResearchRunTranscriptAPI
```
Transcript pages with optional cursor pagination.
#### `work_products`
```python theme={null}
work_products(self) -> ResearchRunWorkProductsAPI
```
Work products produced by the run.
#### `trained_models`
```python theme={null}
trained_models(self) -> ResearchRunTrainedModelsAPI
```
Trained models registered for the run.
#### `artifacts`
```python theme={null}
artifacts(self) -> ResearchRunArtifactsAPI
```
Run artifacts listing and download.
#### `results`
```python theme={null}
results(self) -> ResearchRunResultsAPI
```
Final run results when execution completes.
#### `logs`
```python theme={null}
logs(self) -> ResearchRunLogsAPI
```
Structured run logs.
#### `orchestrator`
```python theme={null}
orchestrator(self) -> ResearchRunOrchestratorAPI
```
Orchestrator readouts for the run.
#### `workspace`
```python theme={null}
workspace(self) -> ResearchRunWorkspaceAPI
```
Run workspace archive download.
#### `code`
```python theme={null}
code(self) -> ResearchRunCodeAPI
```
Run code archive download.
#### `actors`
```python theme={null}
actors(self) -> ResearchRunActorsAPI
```
Runtime actor inventory.
#### `evidence`
```python theme={null}
evidence(self) -> ResearchRunEvidenceAPI
```
Operator evidence bundle for debugging.
#### `authority`
```python theme={null}
authority(self) -> ResearchRunAuthorityAPI
```
Authority and permission readouts.
#### `execution`
```python theme={null}
execution(self) -> ResearchRunExecutionAPI
```
Execution state readouts.
#### `milestones`
```python theme={null}
milestones(self) -> ResearchRunMilestonesAPI
```
Run-scoped milestone readouts.
#### `ticking`
```python theme={null}
ticking(self) -> ResearchRunTickingAPI
```
Run ticking / heartbeat controls.