# Queries, access and diagnostics

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

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/typescript/tour.md) and [TypeScript types](https://beepgrid.com/docs/sdks/typescript/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<T = unknown>(input: QueryInput): Promise<QueryPage<T>>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `input` | `QueryInput` (required) | Typed operation input. See its declaration in the language types reference. |

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

Declared return type: `Promise<QueryPage<T>>`.

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

## capabilities

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

```text
capabilities(input?: { target?: { kind: string; id: string; }; request_id?: string; connection_id?: string; descriptor?: Action; }): Promise<CapabilityResult>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `input` | `{target?:{kind:string;id:string};request_id?:string;connection_id?:string;descriptor?:Action}` (default {}) | Typed operation input. See its declaration in the language types reference. |

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

Declared return type: `Promise<CapabilityResult>`.

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

## access

Inspect effective role assignments for yourself or an authorized subject.

```text
access(subject?: string): Promise<unknown>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `subject` | `string` (default "") | Optional authorized 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.

Declared return type: `Promise<unknown>`.

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

## requestTrace

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

```text
requestTrace(id: string, cursor?: string): Promise<unknown>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |
| `cursor` | `string` (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.

Declared return type: `Promise<unknown>`.

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

## workspace

Read the authenticated workspace's identity and deployment metadata.

```text
workspace(): Promise<unknown>
```

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

Declared return type: `Promise<unknown>`.

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

## account

Read account access and runtime-applied service limits.

```text
account(): Promise<unknown>
```

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

Declared return type: `Promise<unknown>`.

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

## providerCatalog

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

```text
providerCatalog(): Promise<unknown[]>
```

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

Declared return type: `Promise<unknown[]>`.

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

## connectionSetup

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

```text
connectionSetup(id: string): Promise<unknown>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |

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

Declared return type: `Promise<unknown>`.

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

## previewContactPermissions

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

```text
previewContactPermissions(input: ContactPreviewInput): Promise<unknown>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `input` | `ContactPreviewInput` (required) | Typed operation input. See its declaration in the language types reference. |

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

Declared return type: `Promise<unknown>`.

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

## Example

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



```typescript
const input = { collection: 'messages', filters: { conversation_id: sent.conversation_id }, limit: 1 };
let page = await owner.query<Message>(input), seen = [...page.items];
while (page.next_cursor) {
  page = await owner.query<Message>({ ...input, cursor: page.next_cursor });
  seen.push(...page.items);
}
assert.equal(seen.length, 2);
assert.ok((await owner.capabilities({ request_id: blocking.id })).operations.cancel);
assert.ok('roles' in readObject(await owner.access()));
assert.equal(readObject(readObject(await owner.requestTrace(blocking.id)).request).id, blocking.id);
assert.equal(readObject(await owner.workspace()).deployment, 'self_hosted');
assert.ok(readObject(await owner.account()).applied);
assert.ok((await owner.providerCatalog()).length);
const connection = await owner.call<{id:string}>('POST', '/api/v1/connections', {
  name: 'Tour webhook ' + runId, kind: 'webhook', enabled: false,
  config: { url: 'https://example.com/beepgrid' }, secret: crypto.randomUUID() });
assert.ok(await owner.connectionSetup(connection.id));
```