# Queries, access and diagnostics

Python inputs, results, permissions and executable examples for queries, access and diagnostics.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/python/tour.md) and [Python types](https://beepgrid.com/docs/sdks/python/types.md). The example at the end runs after the tour setup.

## query

Page through an authorized collection with supported filters and search.

```text
query(self, collection: str, **options: Any)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `collection` | `str` (required) | One of the documented query collections. |
| `**options` | `keyword fields` (default optional) | Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism. |

**Returns:** QueryPage: items, next_cursor when more scanning remains, order.

**Permissions, lifecycle and errors:** Default limit 50, range 1 to 200. Cursor expires after 24 hours and is tied to actor, scope and query. Continue even if items is empty when next_cursor is present.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## capabilities

Check which operations are available for a target, request, connection or descriptor.

```text
capabilities(self, **options: Any)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `**options` | `keyword fields` (default optional) | Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism. |

**Returns:** observed_at, operations map, request_version and allowed outcomes where applicable.

**Permissions, lifecycle and errors:** This is a current snapshot, not a reservation or permission grant. The actual mutation checks authorization and version again.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## access

Inspect effective role assignments for yourself or an authorized subject.

```text
access(self, subject_id: str='')
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `subject_id` | `str` (default '') | Optional access subject ID. Empty means the current caller. |

**Returns:** Authorized access projection including roles and assignment information.

**Permissions, lifecycle and errors:** Other subjects require management rights. Directory groups, policy roles and chat membership have distinct effects; do not substitute one for another.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## request_trace

Inspect a request's current delivery evidence and execution reports.

```text
request_trace(self, request_id: str, cursor: str='')
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `request_id` | `str` (required) | Canonical durable request ID. This is not a worker delivery ID. |
| `cursor` | `str` (default '') | Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours. |

**Returns:** Request trace projection; delivery evidence may include a next cursor.

**Permissions, lifecycle and errors:** Supply delivery cursor to continue paging. Queued, provider-accepted, replied and executed are different facts. Visibility is projected for the caller.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## workspace

Read the authenticated workspace's identity and deployment metadata.

```text
workspace(self)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |


**Returns:** JSON with scope, company, environment, deployment and schema metadata.

**Permissions, lifecycle and errors:** This endpoint is available to headless OSS clients too; it is not a browser-only feature.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## account

Read account access and runtime-applied service limits.

```text
account(self)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |


**Returns:** JSON account projection including applied state.

**Permissions, lifecycle and errors:** Person-only with account view authority, or operator. Self-hosted account state differs from managed billing and does not require a paid offering.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## provider_catalog

Read the providers actually supported by this engine and their setup fields.

```text
provider_catalog(self)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |


**Returns:** Array of provider capabilities, field definitions and setup modes.

**Permissions, lifecycle and errors:** A catalog entry describes supported functionality, not a configured or live-qualified connection. Generic webhooks are not native adapters.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## connection_setup

Obtain setup instructions and safe callback/manifest information for one connection.

```text
connection_setup(self, connection_id: str)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `connection_id` | `str` (required) | Configured channel connection ID. |

**Returns:** ProviderSetup with supported steps and safe setup values.

**Permissions, lifecycle and errors:** Requires current connection authority. Credentials are not returned as setup text. Provider installation, account linking and contact permissions remain separate.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## preview_contact_permissions

Inspect effective contact access or preview a versioned draft without saving.

```text
preview_contact_permissions(self, subject: dict[str, str], *, rules: list[dict[str, str]] | None=None, version: int=0, targets: list[dict[str, str]] | None=None)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `subject` | `dict[str, str]` (required) | Optional authorized access subject ID. Empty means the current caller. |
| `rules` | `list[dict[str, str]] \| None` (default None) | Directional permission rules granted by this policy role. |
| `version` | `int` (default 0) | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `targets` | `list[dict[str, str]] \| None` (default None) | Explicit targets for a private batch or shared chat. These have different audience semantics. |

**Returns:** Current dedicated policy, effective contact actions and sources, warnings and can_save.

**Permissions, lifecycle and errors:** Omit rules to observe; use an empty list to preview defaults. Reload on conflict. A preview grants no authority.

[Working Python example](https://beepgrid.com/docs/sdks/python/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/python/tour.md). Assertions check the returned data; the full tour is a runnable program.



```python
page = owner.query('messages', filters={'conversation_id': sent['conversation_id']}, limit=1)
seen = list(page['items'])
while page.get('next_cursor'):
    page = owner.query('messages', filters={'conversation_id': sent['conversation_id']}, limit=1, cursor=page['next_cursor'])
    seen.extend(page['items'])
assert len(seen) == 2
assert owner.capabilities(request_id=blocking['id'])['operations']['cancel']
assert 'roles' in owner.access()
assert owner.request_trace(blocking['id'])['request']['id'] == blocking['id']
assert owner.workspace()['deployment'] == 'self_hosted'
assert 'applied' in owner.account()
assert owner.provider_catalog()
connection = owner.call('POST', '/api/v1/connections', {
    'name': 'Tour webhook ' + run_id, 'kind': 'webhook', 'enabled': False,
    'config': {'url': 'https://example.com/beepgrid'}, 'secret': uuid.uuid4().hex})
assert owner.connection_setup(connection['id'])
```