> ## 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.
# swarm_readouts
# `synth_ai.research.swarm_readouts`
Nested run readout namespaces on `ResearchSwarmHandle`.
## Classes
### `ResearchSwarmUsageActorsAPI`
Per-actor usage breakdown for a swarm.
**Methods:**
#### `get`
```python theme={null}
get(self) -> SmrRunActorUsage
```
Return token and cost usage grouped by runtime actor.
### `ResearchSwarmUsageCostAPI`
Run-level cost summary readouts.
**Methods:**
#### `get`
```python theme={null}
get(self) -> SmrRunCostSummary
```
Return aggregated cost fields for the swarm.
### `ResearchSwarmUsageLimitsAPI`
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).
### `ResearchSwarmUsageAPI`
Token, cost, and limit readouts for a swarm.
**Methods:**
#### `actors`
```python theme={null}
actors(self) -> ResearchSwarmUsageActorsAPI
```
Per-actor usage slice.
#### `cost`
```python theme={null}
cost(self) -> ResearchSwarmUsageCostAPI
```
Run cost summary slice.
#### `limits`
```python theme={null}
limits(self) -> ResearchSwarmUsageLimitsAPI
```
Resource limit and progress slice.
#### `get`
```python theme={null}
get(self) -> SmrRunUsage
```
Return canonical usage totals for the swarm.
### `ResearchSwarmProgressAPI`
High-level progress summary for dashboards and polling loops.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return the backward-compatible raw progress payload.
#### `get_typed`
```python theme={null}
get_typed(self) -> ResearchSwarmProgress
```
Return typed state, phase, stalls, tasks, and recommended actions.
### `ResearchSwarmSnapshotsAPI`
Observability snapshots (control vs full detail).
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return an observability snapshot for the swarm.
**Args:**
* `detail`: `"control"` for operator dashboard fields or `"full"` for
the expanded observability projection.
### `ResearchSwarmEventsObjectivesAPI`
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.
### `ResearchSwarmEventsTasksAPI`
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.
### `ResearchSwarmEventsAPI`
Structured and streaming runtime events for a swarm.
**Methods:**
#### `objectives`
```python theme={null}
objectives(self) -> ResearchSwarmEventsObjectivesAPI
```
Objective-scoped event list.
#### `tasks`
```python theme={null}
tasks(self) -> ResearchSwarmEventsTasksAPI
```
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.
### `ResearchSwarmTasksAPI`
Task summaries attached to a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List task summaries for the swarm.
**Args:**
* `kind`: Optional task kind filter.
* `limit`: Maximum summaries to return.
### `ResearchSwarmMessageQueueMessagesAPI`
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.
### `ResearchSwarmMessageQueueThreadsAPI`
Message queue threads for operator steering.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List message queue threads for the swarm.
### `ResearchSwarmMessageQueueInteractionsAPI`
Pending and completed message queue interactions.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List interactions, optionally filtered by status.
### `ResearchSwarmMessageQueueAPI`
Operator steering via threads, messages, and interactions.
**Methods:**
#### `messages`
```python theme={null}
messages(self) -> ResearchSwarmMessageQueueMessagesAPI
```
Outbound messages API.
#### `threads`
```python theme={null}
threads(self) -> ResearchSwarmMessageQueueThreadsAPI
```
Thread listing API.
#### `interactions`
```python theme={null}
interactions(self) -> ResearchSwarmMessageQueueInteractionsAPI
```
Interaction listing API.
### `ResearchSwarmRuntimeMessagesAPI`
Runtime messages visible to operators and viewers.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[dict[str, Any]]
```
List runtime messages for the swarm.
**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.
### `ResearchSwarmTranscriptAPI`
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.
### `ResearchSwarmMilestonesAPI`
Swarm-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.
### `ResearchSwarmWorkProductsContentAPI`
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.
### `ResearchSwarmTrainedModelsAPI`
Trained model artifacts produced by a run.
**Methods:**
#### `list`
```python theme={null}
list(self) -> List[Any]
```
List trained models registered for the swarm.
### `ResearchSwarmWorkProductsEvalPackagesAPI`
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.
### `ResearchSwarmWorkProductsAPI`
Work products and derived outputs from a run.
**Methods:**
#### `content`
```python theme={null}
content(self) -> ResearchSwarmWorkProductsContentAPI
```
Download work product bodies.
#### `eval_packages`
```python theme={null}
eval_packages(self) -> ResearchSwarmWorkProductsEvalPackagesAPI
```
List container eval packages.
#### `list`
```python theme={null}
list(self) -> List[ResearchWorkProduct]
```
List work product metadata for the swarm.
### `ResearchSwarmHostedArtifactsAPI`
Hosted artifact receipt and operator actions for a swarm.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return hosted artifact status for this run.
#### `content`
```python theme={null}
content(self, hosted_artifact_id: str | None = None) -> str | bytes
```
Fetch hosted HTML for this run's artifact.
#### `publish_public`
```python theme={null}
publish_public(self, slug: str) -> dict[str, Any]
```
Promote this run's hosted artifact to the public index.
#### `assign_reviewer`
```python theme={null}
assign_reviewer(self, reason: str) -> dict[str, Any]
```
Dispatch an artifact\_reviewer for this run's hosted artifact.
### `ResearchSwarmArtifactsManifestAPI`
Artifact manifest for a swarm.
**Methods:**
#### `get`
```python theme={null}
get(self) -> ResearchArtifactManifest
```
Return the artifact manifest describing available run outputs.
### `ResearchSwarmArtifactsContentAPI`
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.
### `ResearchSwarmArtifactsAPI`
Run artifacts listing, manifest, and content download.
**Methods:**
#### `manifest`
```python theme={null}
manifest(self) -> ResearchSwarmArtifactsManifestAPI
```
Artifact manifest API.
#### `content`
```python theme={null}
content(self) -> ResearchSwarmArtifactsContentAPI
```
Artifact content download API.
#### `list`
```python theme={null}
list(self) -> List[ResearchArtifact]
```
List artifacts for the swarm with optional type filter.
### `ResearchSwarmResultsAPI`
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.
### `ResearchSwarmLogsAPI`
Structured run logs for debugging and audit.
**Methods:**
#### `list`
```python theme={null}
list(self) -> dict[str, Any]
```
List log records with optional cursor pagination.
### `ResearchSwarmOrchestratorAPI`
Orchestrator state and routing metadata for a swarm.
**Methods:**
#### `get`
```python theme={null}
get(self) -> dict[str, Any]
```
Return orchestrator readouts for the swarm.
### `ResearchSwarmWorkspaceAPI`
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.
### `ResearchSwarmCodeAPI`
Run code archive download.
**Methods:**
#### `download`
```python theme={null}
download(self, path: str) -> dict[str, Any]
```
Download run code to the given local path.
### `ResearchSwarmActorsAPI`
Runtime actor inventory for a swarm.
**Methods:**
#### `list`
```python theme={null}
list(self) -> dict[str, Any]
```
List actors participating in the run.
### `ResearchSwarmEvidenceAPI`
Operator evidence bundle for debugging run behavior.
**Methods:**
#### `get`
```python theme={null}
get(self) -> SmrRunOperatorEvidence
```
Return operator evidence with optional per-section limits.
### `ResearchSwarmAuthorityAPI`
Authority and permission readouts for operators.
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return authority readouts for the swarm.
**Args:**
* `include_runtime_authority`: Include live runtime authority fields when
available.
### `ResearchSwarmExecutionAPI`
Execution state and worker routing for a swarm.
**Methods:**
#### `get`
```python theme={null}
get(self, **kwargs: Any) -> Any
```
Return execution readouts for the swarm.
### `ResearchSwarmTickingAPI`
Run ticking / heartbeat controls for long-running workloads.
**Methods:**
#### `get`
```python theme={null}
get(self) -> Any
```
Return current ticking state for the swarm.
#### `set`
```python theme={null}
set(self, update: Any = None, **kwargs: Any) -> Any
```
Update ticking configuration for the swarm.
### `ResearchSwarmReadoutsMixin`
Lazy nested readout namespaces on :class:`ResearchSwarmHandle`.
Access via `handle.usage`, `handle.progress`, `handle.snapshots`,
`handle.transcript`, `handle.message_queue`, etc.
**Methods:**
#### `usage`
```python theme={null}
usage(self) -> ResearchSwarmUsageAPI
```
Usage, cost, and limit readouts.
#### `progress`
```python theme={null}
progress(self) -> ResearchSwarmProgressAPI
```
Coarse progress for polling UIs.
#### `snapshots`
```python theme={null}
snapshots(self) -> ResearchSwarmSnapshotsAPI
```
Observability snapshots (control or full).
#### `events`
```python theme={null}
events(self) -> ResearchSwarmEventsAPI
```
Structured and streaming runtime events.
#### `tasks`
```python theme={null}
tasks(self) -> ResearchSwarmTasksAPI
```
Task summaries for the swarm.
#### `message_queue`
```python theme={null}
message_queue(self) -> ResearchSwarmMessageQueueAPI
```
Operator message queue threads and outbound messages.
#### `messages`
```python theme={null}
messages(self) -> ResearchSwarmRuntimeMessagesAPI
```
Runtime messages visible to operators.
#### `transcript`
```python theme={null}
transcript(self) -> ResearchSwarmTranscriptAPI
```
Transcript pages with optional cursor pagination.
#### `work_products`
```python theme={null}
work_products(self) -> ResearchSwarmWorkProductsAPI
```
Work products produced by the run.
#### `hosted_artifact`
```python theme={null}
hosted_artifact(self) -> ResearchSwarmHostedArtifactsAPI
```
Hosted Open Research artifact receipt for the swarm.
#### `trained_models`
```python theme={null}
trained_models(self) -> ResearchSwarmTrainedModelsAPI
```
Trained models registered for the swarm.
#### `artifacts`
```python theme={null}
artifacts(self) -> ResearchSwarmArtifactsAPI
```
Run artifacts listing and download.
#### `results`
```python theme={null}
results(self) -> ResearchSwarmResultsAPI
```
Final run results when execution completes.
#### `logs`
```python theme={null}
logs(self) -> ResearchSwarmLogsAPI
```
Structured run logs.
#### `orchestrator`
```python theme={null}
orchestrator(self) -> ResearchSwarmOrchestratorAPI
```
Orchestrator readouts for the swarm.
#### `workspace`
```python theme={null}
workspace(self) -> ResearchSwarmWorkspaceAPI
```
Run workspace archive download.
#### `code`
```python theme={null}
code(self) -> ResearchSwarmCodeAPI
```
Run code archive download.
#### `actors`
```python theme={null}
actors(self) -> ResearchSwarmActorsAPI
```
Runtime actor inventory.
#### `evidence`
```python theme={null}
evidence(self) -> ResearchSwarmEvidenceAPI
```
Operator evidence bundle for debugging.
#### `authority`
```python theme={null}
authority(self) -> ResearchSwarmAuthorityAPI
```
Authority and permission readouts.
#### `execution`
```python theme={null}
execution(self) -> ResearchSwarmExecutionAPI
```
Execution state readouts.
#### `milestones`
```python theme={null}
milestones(self) -> ResearchSwarmMilestonesAPI
```
Swarm-scoped milestone readouts.
#### `ticking`
```python theme={null}
ticking(self) -> ResearchSwarmTickingAPI
```
Run ticking / heartbeat controls.