> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Read workflows and stream runs (client.workflows).

### WorkflowsResource

```python
class WorkflowsResource(http: ~modus._http.HttpClient, agent_http: ~modus._http.HttpClient, config: ~modus._config.ModusConfig, ops: ~modus.resources.workflows.workflows.WorkflowsOperations = WorkflowsOperations(list='WorkflowsController_list', get='WorkflowsController_get', runs=RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'), stream_session=<function workflow_stream_session>, stream_session_async=<function workflow_stream_session_async>))
```

Bases: `object`

Read access to Modus workflows.

client.workflows.list() → Page\[Agent] client.workflows.get(workflow\_id) → Agent

To create, update, or deploy workflows use modus.management.ModusManagement.

#### list()

```python
list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, type: AgentType | None = None, view: Literal['active', 'draft'] | None = None, include_variation: bool | None = None) → Page[WorkflowDto]
```

List workflows in the organisation.

* Parameters:

  * **page\_size** – Items per page (default 25).

  * **page\_token** – Opaque token from a previous page’s `next_page_token`.

  * **search** – Case-insensitive substring filter on the workflow name.

  * **type** – Filter by workflow type: `"task"` or `"workflow"`.

  * **view** – Variation view — `"active"` (deployed) or `"draft"`.

  * **include\_variation** – Include variation payload on each list row.

#### get()

```python
get(workflow_id: int | str, *, view: Literal['active', 'draft'] | None = None) → WorkflowDto
```

Retrieve a workflow by ID or slug.

* Parameters:

  **view** – Variation view — `"active"` (deployed) or `"draft"`.

* Raises:

  [**NotFoundError**](<> "modus._exceptions.NotFoundError") – if no workflow with this ID/slug exists.

#### chat\_stream()

```python
chat_stream(workflow_id: int | str, message: str, *, model: str, thread_id: str | None = None, version: Literal['published', 'draft'] | str | None = None) → ChatStream
```

Send a message to a workflow and stream the reply token by token.

* Parameters:

  * **workflow\_id** – Workflow ID or slug.

  * **message** – The message to send.

  * **model** – Model to run this message with (required). One of the supported model IDs, e.g. `"claude-sonnet-5"` or `"gpt-5.5"`.

  * **thread\_id** – Continue an existing conversation; omit to start a new one.

  * **version** – Run a specific variation — `"published"` or `"draft"`.

* Returns:

  ChatStream you can iterate for text chunks; the final result carries the `thread_id`.

### AsyncWorkflowsResource

```python
class AsyncWorkflowsResource(http: ~modus._http.AsyncHttpClient, agent_http: ~modus._http.AsyncHttpClient, config: ~modus._config.ModusConfig, ops: ~modus.resources.workflows.workflows.WorkflowsOperations = WorkflowsOperations(list='WorkflowsController_list', get='WorkflowsController_get', runs=RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'), stream_session=<function workflow_stream_session>, stream_session_async=<function workflow_stream_session_async>))
```

Bases: `object`

Async read access to Modus workflows.

await client.workflows.list() → AsyncPage\[Agent] await client.workflows.get(workflow\_id) → Agent

To create, update, or deploy workflows use modus.management.ModusManagement.

#### list()

```python
async list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, type: AgentType | None = None, view: Literal['active', 'draft'] | None = None, include_variation: bool | None = None) → AsyncPage[WorkflowDto]
```

List workflows in the organisation.

* Parameters:

  * **page\_size** – Items per page (default 25).

  * **page\_token** – Opaque token from a previous page’s `next_page_token`.

  * **search** – Case-insensitive substring filter on the workflow name.

  * **type** – Filter by workflow type: `"task"` or `"workflow"`.

  * **view** – Variation view — `"active"` (deployed) or `"draft"`.

  * **include\_variation** – Include variation payload on each list row.

#### get()

```python
async get(workflow_id: int | str, *, view: Literal['active', 'draft'] | None = None) → WorkflowDto
```

Retrieve a workflow by ID or slug.

* Parameters:

  **view** – Variation view — `"active"` (deployed) or `"draft"`.

* Raises:

  [**NotFoundError**](<> "modus._exceptions.NotFoundError") – if no workflow with this ID/slug exists.

#### chat\_stream()

```python
chat_stream(workflow_id: int | str, message: str, *, model: str, thread_id: str | None = None, version: Literal['published', 'draft'] | str | None = None) → AsyncChatStream
```

Send a message to a workflow and stream the reply token by token.

* Parameters:

  * **workflow\_id** – Workflow ID or slug.

  * **message** – The message to send.

  * **model** – Model to run this message with (required). One of the supported model IDs, e.g. `"claude-sonnet-5"` or `"gpt-5.5"`.

  * **thread\_id** – Continue an existing conversation; omit to start a new one.

  * **version** – Run a specific variation — `"published"` or `"draft"`.

* Returns:

  AsyncChatStream you can iterate for text chunks; the final result carries the `thread_id`.

### WorkflowRunsResource

```python
class WorkflowRunsResource(http: HttpClient, config: ModusConfig, ops: RunOperations = RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'))
```

Bases: `object`

#### list()

```python
list(workflow_id: int | str, *, page_size: int = 25, page_token: str | None = None, status: Literal['running', 'awaiting_human', 'completed', 'error', 'cancelled', 'all_executions'] | str | None = None, timeframe: Literal['last_hour', 'last_day', 'last_week'] | str | None = None, approval_scope: Literal['mine', 'all'] | str | None = None, search: str | None = None) → Page[AutomationRunListItemDto]
```

List runs for a workflow.

* Parameters:

  * **workflow\_id** – Workflow ID or slug.

  * **page\_size** – Maximum number of items to return (default 25, max 100).

  * **page\_token** – Token from a previous page’s `next_page_token`; omit for the first page.

  * **status** – Filter by run status (e.g. `"running"`, `"awaiting_human"`, `"completed"`, `"error"`, `"cancelled"`, `"all_executions"`).

  * **timeframe** – Filter by time window (e.g. `"last_hour"`, `"last_day"`, `"last_week"`).

  * **approval\_scope** – When `status="awaiting_human"`, scope to `"mine"` or `"all"`.

  * **search** – Free-text search filter.

#### active()

```python
active(*, page_size: int = 50, page_token: str | None = None) → Page[ActiveConversationRunDto]
```

List active conversation runs for the current user.

* Parameters:

  * **page\_size** – Maximum number of active runs to return (default 50, max 100).

  * **page\_token** – Token from a previous page’s `next_page_token`; omit for the first page.

#### active\_by\_session()

```python
active_by_session(session_ids: Sequence[str]) → List[ActiveConversationRunDto]
```

Return active runs for the supplied conversation thread ids.

* Parameters:

  **session\_ids** – Conversation thread ids to check; blanks and duplicates are ignored.

#### get()

```python
get(workflow_id: int | str, run_id: str, *, temporal_run_id: str | None = None) → GetAutomationRunResponseDto
```

Retrieve a Modus workflow run by ID.

* Parameters:

  * **workflow\_id** – Modus workflow ID or slug.

  * **run\_id** – Run ID.

  * **temporal\_run\_id** – Optional Temporal run ID when disambiguating.

#### create()

```python
create(workflow_id: int | str, body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Start a workflow run and stream its events.

* Parameters:

  * **workflow\_id** – Workflow ID or slug.

  * **body** – Run request fields such as message, sessionId, config, and runId.

#### create\_scope()

```python
create_scope(scope_id: int | str, body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Start a scope run and stream its events.

* Parameters:

  * **scope\_id** – Scope ID or slug.

  * **body** – Run request fields such as message, sessionId, config, and runId.

#### create\_modus()

```python
create_modus(body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Start a Modus run and stream its events.

* Parameters:

  **body** – Run request fields such as message, sessionId, config, and runId.

#### resume()

```python
resume(run_id: str, body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Resume a paused run and stream its events.

* Parameters:

  * **run\_id** – Run ID to resume.

  * **body** – Resume request fields including the decision and message.

#### cancel()

```python
cancel(run_id: str, body: Mapping[str, Any] | None = None) → None
```

Cancel a run.

* Parameters:

  * **run\_id** – Run ID to cancel.

  * **body** – Optional cancellation details.

#### interrupt()

```python
interrupt(run_id: str, body: Mapping[str, Any] | None = None) → None
```

Interrupt a run.

* Parameters:

  * **run\_id** – Run ID to interrupt.

  * **body** – Optional interruption details.

#### edit\_queued()

```python
edit_queued(run_id: str, body: Mapping[str, Any] | None = None) → None
```

Edit a queued run.

* Parameters:

  * **run\_id** – Run ID to edit.

  * **body** – Optional queued-run edit details.

#### events()

```python
events(run_id: str) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Stream run lifecycle events.

* Parameters:

  **run\_id** – Run ID to follow.

#### stream()

```python
stream(run_id: str) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Stream run output events.

* Parameters:

  **run\_id** – Run ID to follow.

### AsyncWorkflowRunsResource

```python
class AsyncWorkflowRunsResource(http: AsyncHttpClient, config: ModusConfig, ops: RunOperations = RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'))
```

Bases: `object`

#### list()

```python
async list(workflow_id: int | str, *, page_size: int = 25, page_token: str | None = None, status: Literal['running', 'awaiting_human', 'completed', 'error', 'cancelled', 'all_executions'] | str | None = None, timeframe: Literal['last_hour', 'last_day', 'last_week'] | str | None = None, approval_scope: Literal['mine', 'all'] | str | None = None, search: str | None = None) → AsyncPage[AutomationRunListItemDto]
```

List runs for a workflow.

* Parameters:

  * **workflow\_id** – Workflow ID or slug.

  * **page\_size** – Maximum number of items to return (default 25, max 100).

  * **page\_token** – Token from a previous page’s `next_page_token`; omit for the first page.

  * **status** – Filter by run status (e.g. `"running"`, `"awaiting_human"`, `"completed"`, `"error"`, `"cancelled"`, `"all_executions"`).

  * **timeframe** – Filter by time window (e.g. `"last_hour"`, `"last_day"`, `"last_week"`).

  * **approval\_scope** – When `status="awaiting_human"`, scope to `"mine"` or `"all"`.

  * **search** – Free-text search filter.

#### active()

```python
async active(*, page_size: int = 50, page_token: str | None = None) → AsyncPage[ActiveConversationRunDto]
```

List active conversation runs for the current user.

* Parameters:

  * **page\_size** – Maximum number of active runs to return (default 50, max 100).

  * **page\_token** – Token from a previous page’s `next_page_token`; omit for the first page.

#### active\_by\_session()

```python
async active_by_session(session_ids: Sequence[str]) → List[ActiveConversationRunDto]
```

Return active runs for the supplied conversation thread ids.

* Parameters:

  **session\_ids** – Conversation thread ids to check; blanks and duplicates are ignored.

#### get()

```python
async get(workflow_id: int | str, run_id: str, *, temporal_run_id: str | None = None) → GetAutomationRunResponseDto
```

Retrieve a Modus workflow run by ID.

* Parameters:

  * **workflow\_id** – Modus workflow ID or slug.

  * **run\_id** – Run ID.

  * **temporal\_run\_id** – Optional Temporal run ID when disambiguating.

#### create()

```python
async create(workflow_id: int | str, body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Start a workflow run and stream its events.

* Parameters:

  * **workflow\_id** – Workflow ID or slug.

  * **body** – Run request fields such as message, sessionId, config, and runId.

#### create\_scope()

```python
async create_scope(scope_id: int | str, body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Start a scope run and stream its events.

* Parameters:

  * **scope\_id** – Scope ID or slug.

  * **body** – Run request fields such as message, sessionId, config, and runId.

#### create\_modus()

```python
async create_modus(body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Start a Modus run and stream its events.

* Parameters:

  **body** – Run request fields such as message, sessionId, config, and runId.

#### resume()

```python
async resume(run_id: str, body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Resume a paused run and stream its events.

* Parameters:

  * **run\_id** – Run ID to resume.

  * **body** – Resume request fields including the decision and message.

#### cancel()

```python
async cancel(run_id: str, body: Mapping[str, Any] | None = None) → None
```

Cancel a run.

* Parameters:

  * **run\_id** – Run ID to cancel.

  * **body** – Optional cancellation details.

#### interrupt()

```python
async interrupt(run_id: str, body: Mapping[str, Any] | None = None) → None
```

Interrupt a run.

* Parameters:

  * **run\_id** – Run ID to interrupt.

  * **body** – Optional interruption details.

#### edit\_queued()

```python
async edit_queued(run_id: str, body: Mapping[str, Any] | None = None) → None
```

Edit a queued run.

* Parameters:

  * **run\_id** – Run ID to edit.

  * **body** – Optional queued-run edit details.

#### events()

```python
async events(run_id: str) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Stream run lifecycle events.

* Parameters:

  **run\_id** – Run ID to follow.

#### stream()

```python
async stream(run_id: str) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]
```

Stream run output events.

* Parameters:

  **run\_id** – Run ID to follow.