# Queries, access and diagnostics

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

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

## Query

Page through an authorized collection with supported filters and search.

```text
func (c *Client) Query(ctx context.Context, in QueryInput) (QueryPage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `in` | `QueryInput` (required) | Typed operation input. Every field is listed 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.

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

## Capabilities

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

```text
func (c *Client) Capabilities(ctx context.Context, in CapabilityInput) (CapabilityResult, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `in` | `CapabilityInput` (required) | Typed operation input. Every field is listed 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.

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

## Access

Inspect effective role assignments for yourself or an authorized subject.

```text
func (c *Client) Access(ctx context.Context, subject string) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `subject` | `string` (required) | 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.

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

## RequestTrace

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

```text
func (c *Client) RequestTrace(ctx context.Context, id, cursor string) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |
| `cursor` | `string` (required) | 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 Go example](https://beepgrid.com/docs/sdks/go/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Workspace

Read the authenticated workspace's identity and deployment metadata.

```text
func (c *Client) Workspace(ctx context.Context) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |

**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 Go example](https://beepgrid.com/docs/sdks/go/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Account

Read account access and runtime-applied service limits.

```text
func (c *Client) Account(ctx context.Context) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |

**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 Go example](https://beepgrid.com/docs/sdks/go/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## ProviderCatalog

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

```text
func (c *Client) ProviderCatalog(ctx context.Context) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |

**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 Go example](https://beepgrid.com/docs/sdks/go/queries/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## ConnectionSetup

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

```text
func (c *Client) ConnectionSetup(ctx context.Context, id string) (json.RawMessage, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `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.

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

## PreviewContactPermissions

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

```text
func (c *Client) PreviewContactPermissions(ctx context.Context, in ContactPreviewInput) (map[string]any, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `in` | `ContactPreviewInput` (required) | Typed operation input. Every field is listed 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.

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

## Example

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



```go
input := beepgrid.QueryInput{Collection: "messages", Filters: map[string]string{"conversation_id": sent.ConversationID}, Limit: 1}
page := must(owner.Query(ctx, input))
seen := len(page.Items)
for page.NextCursor != "" {
	input.Cursor = page.NextCursor
	page = must(owner.Query(ctx, input))
	seen += len(page.Items)
}
check(seen == 2)
check(must(owner.Capabilities(ctx, beepgrid.CapabilityInput{RequestID: blocking.ID})).Operations["cancel"])
check(decoded(must(owner.Access(ctx, "")))["roles"] != nil)
check(decoded(must(owner.RequestTrace(ctx, blocking.ID, "")))["request"] != nil)
check(decoded(must(owner.Workspace(ctx)))["deployment"] == "self_hosted")
check(decoded(must(owner.Account(ctx)))["applied"] != nil)
check(len(must(owner.ProviderCatalog(ctx))) > 0)
var connection struct {
	ID string `json:"id"`
}
if err := owner.Do(ctx, "POST", "/api/v1/connections", map[string]any{"name": "Tour webhook " + runID, "kind": "webhook", "enabled": false, "config": map[string]string{"url": "https://example.com/beepgrid"}, "secret": beepgrid.Key()}, &connection, ""); err != nil {
	panic(err)
}
check(len(must(owner.ConnectionSetup(ctx, connection.ID))) > 0)
```