# Queries, filters and pagination

Page every supported collection using the actual filter and ordering contract.

`query` returns `{items, next_cursor?, order}` under current authorization. Default `limit` is 50; valid values are 1 through 200. `search` is at most 200 characters and matches supported textual resource metadata, not arbitrary nested JSON or SQL.

## Collections and filters

All collections support the exact `id` filter. Other supported filters are below; values are strings. Unknown combinations are rejected rather than silently ignored.

| Collection | Additional filters | Returned items |
| --- | --- | --- |
| `people`, `agents`, `services` | `disabled`, `project`, `type`, `parent_id`, `enrolled_by`, `department`, `manager_id`, `group_id`, `role_id`; `agents` also supports `presence` | Identity records, with current visible metadata |
| `groups` | `purpose`, `member_id` | Directory groups |
| `roles` | None beyond `id` | Policy roles |
| `connections` | `kind` | Safe provider configuration |
| `destinations` | `connection_id`, `principal_id` | Delivery destinations |
| `credentials` | `kind`, `principal_id` | Credential metadata, not plaintext tokens |
| `instances` | `agent_id` | Runtime presence/progress observations |
| `requests` | `conversation_id`, `state`, `kind`, `recipient_id`, `requester_id` | Current requests and response projection |
| `conversations` | `participant_id` | Currently visible summaries |
| `messages` | Required `conversation_id` | Currently disclosed canonical messages |
| `answers` | None beyond `id` | Authorized informational publications |
| `executions` | `state`, `request_id` | Execution observations |
| `deliveries` | `state`, `connection_id`, `operation_id`, `request_id` | Authorized transport evidence |
| `delivery_attempts` | Required `delivery_id` | Recorded transport attempts |
| `attachments` | Required `conversation_id` | Currently visible file metadata |
| `overseer_plans` | None beyond `id` | Current caller's Coordinator plans |

`disabled` accepts `true` or `false`. Agent `presence` accepts `connected`, `stale` or `offline`. Group `purpose` accepts `contacts`, `team` or `agent_role`. Role/group filters require visibility of the role/group; they do not expose hidden membership.

## Ordering

Most collections use stable ascending IDs. Messages and delivery attempts use chronological creation order; Coordinator plans use descending creation order. Conversations use descending recent activity. Read `order` from the result rather than assuming every collection uses the same order.

## Complete pagination

Keep collection, search, filters and limit unchanged while using `next_cursor`. Cursors are opaque, bound to the actor/workspace/query and expire after 24 hours. Restart the query if the cursor expires or you intentionally change the filters.

Continue until `next_cursor` is absent, even when `items` is empty. Authorization filtering can hide every record in a scanned page while later visible records still exist. Never stop a loop only because the current items array is empty.

The SDK examples include a real two-page message history:

[Python](https://beepgrid.com/docs/sdks/python/queries/#example) · [TypeScript](https://beepgrid.com/docs/sdks/typescript/queries/#example) · [Go](https://beepgrid.com/docs/sdks/go/queries/#example)