> ## 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.

# Scopes

> Read and chat with scopes (client.scopes).

### ScopesResource

```python
class ScopesResource(http: ~modus._http.HttpClient, agent_http: ~modus._http.HttpClient, config: ~modus._config.ModusConfig, ops: ~modus.resources.scopes.scopes.ScopesOperations = ScopesOperations(resource='scopes', list='ScopesController_list', get='ScopesController_get', compose='ScopeContextController_compose', conversations=ScopeConversationsOperations(list='ScopeConversationsController_list', get='ScopeConversationsController_get'), stream_session=<function scope_stream_session>, stream_session_async=<function scope_stream_session_async>))
```

Bases: `object`

Read access to Modus scopes.

client.scopes.list() → Page\[Skill] client.scopes.get(scope\_id) → Skill client.scopes.conversations(scope\_id).list() → Page\[ConversationListItem] client.scopes.conversations(scope\_id).get(thread) → Conversation

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

#### conversations()

```python
conversations(scope_id: int | str) → ScopeConversationsResource
```

Return the conversations sub-resource scoped to `scope_id`.

#### list()

```python
list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, view: Literal['active', 'draft'] | None = None, manager_id: int | None = None) → Page[ScopeDto]
```

List scopes 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 scope name.

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

  * **manager\_id** – Return only scopes supervised by this manager scope id.

#### get()

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

Retrieve a scope by ID or slug.

* Parameters:

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

* Raises:

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

#### chat()

```python
chat(scope_id: int | str, message: str, *, model: str, thread_id: str | None = None) → SkillChatResponseDto
```

Send a message to a scope and get the complete reply.

* Parameters:

  * **scope\_id** – Scope 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.

* Returns:

  ChatResult with the reply `content` and the `thread_id` to continue the conversation.

#### chat\_stream()

```python
chat_stream(scope_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 scope and stream the reply token by token.

* Parameters:

  * **scope\_id** – Scope 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`.

#### get\_context()

```python
get_context(scope_id: int | str, message: str, *, limit: int | None = None) → ComposeSkillContextResponseDto
```

Return composed context Modus would use for a scope query, without running chat.

* Parameters:

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

  * **message** – Natural-language query used to select context.

  * **limit** – Optional cap on structured fallback items when no markdown summary exists.

### AsyncScopesResource

```python
class AsyncScopesResource(http: ~modus._http.AsyncHttpClient, agent_http: ~modus._http.AsyncHttpClient, config: ~modus._config.ModusConfig, ops: ~modus.resources.scopes.scopes.ScopesOperations = ScopesOperations(resource='scopes', list='ScopesController_list', get='ScopesController_get', compose='ScopeContextController_compose', conversations=ScopeConversationsOperations(list='ScopeConversationsController_list', get='ScopeConversationsController_get'), stream_session=<function scope_stream_session>, stream_session_async=<function scope_stream_session_async>))
```

Bases: `object`

Async read access to Modus scopes.

await client.scopes.list() → AsyncPage\[Skill] await client.scopes.get(scope\_id) → Skill await client.scopes.conversations(scope\_id).list() → AsyncPage\[ConversationListItem]

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

#### conversations()

```python
conversations(scope_id: int | str) → AsyncScopeConversationsResource
```

Return the conversations sub-resource scoped to `scope_id`.

#### list()

```python
async list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, view: Literal['active', 'draft'] | None = None, manager_id: int | None = None) → AsyncPage[ScopeDto]
```

List scopes 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 scope name.

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

  * **manager\_id** – Return only scopes supervised by this manager scope id.

#### get()

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

Retrieve a scope by ID or slug. See the sync `get` for argument details.

#### chat()

```python
async chat(scope_id: int | str, message: str, *, model: str, thread_id: str | None = None) → SkillChatResponseDto
```

Send a message to a scope and get the complete reply. See the sync `chat` for argument details.

#### chat\_stream()

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

Stream a scope reply token by token. See the sync `chat_stream` for argument details.

#### get\_context()

```python
async get_context(scope_id: int | str, message: str, *, limit: int | None = None) → ComposeSkillContextResponseDto
```

Return composed context Modus would use for a scope query, without running chat.

* Parameters:

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

  * **message** – Natural-language query used to select context.

  * **limit** – Optional cap on structured fallback items when no markdown summary exists.