Queries, filters and pagination
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
Section titled “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
Section titled “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
Section titled “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 · TypeScript · Go