retrieve_entities
Retrieve entities with filtered lists by type, pagination, search, and snapshot filters. Supports lexical/semantic queries, date and status filters, and lightweight responses.
Instructions
Use this when you need filtered entity lists (by type, pagination, and optional published/date filters) or lexical/semantic retrieval via search. Strict mode: search cannot be combined with non-default sorting or published filters. Set include_snapshots=false for lightweight responses that omit snapshot/provenance/raw_fragments. Use snapshot_filters to filter by snapshot field values server-side (e.g. { "status": { "op": "eq", "value": "active" } } for active entities). Compatibility aliases search_query and query are accepted but search is canonical.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | Optional single entity type filter (for example: post, task, contact). Combined as a union with `entity_types` when both are supplied. | |
| entity_types | No | Optional multi-type filter. When non-empty, results are restricted to entities whose type is in this list (IN filter), OR-combined with `entity_type`. An empty array is treated as no filter. | |
| search | No | Canonical free-text query for lexical/semantic retrieval. Cannot be combined with published filters or non-default sorting. | |
| search_query | No | Compatibility alias for `search`. | |
| query | No | Compatibility alias for `search`. | |
| similarity_threshold | No | Semantic distance threshold when `search` is used. Lower is stricter (typical 1.0-1.05). | |
| limit | No | Maximum number of entities to return (default 100). | |
| offset | No | Pagination offset (default 0). | |
| sort_by | No | Sort field. Non-default values cannot be combined with `search`. Predefined values: `entity_id`, `canonical_name`, `observation_count`, `last_observation_at`, `submitted_at` (orders by `snapshot.created_at`). In addition, `snapshot.<field>` is supported for any snapshot field (e.g. `snapshot.period_end` for time-series entity types such as `usage_digest`). The field value is sorted lexicographically as a string, so ISO-8601 date strings must use a consistent format so that lexicographic order matches temporal order. | |
| sort_order | No | Sort direction. `desc` cannot be combined with `search`. | |
| published | No | Filter by snapshot.published. Cannot be combined with `search`. | |
| published_after | No | Inclusive lower bound for snapshot.published_date (ISO date/datetime). Cannot be combined with `search`. | |
| published_before | No | Inclusive upper bound for snapshot.published_date (ISO date/datetime). Cannot be combined with `search`. | |
| include_snapshots | No | When false, omit snapshot/provenance/raw_fragments payloads for lightweight responses. | |
| include_merged | No | Whether to include merged entities (default false). | |
| user_id | No | Optional explicit user ID (normally inferred from auth context). | |
| updated_since | No | ISO 8601 timestamp. Return only entities whose updated_at is greater than or equal to this value. | |
| created_since | No | ISO 8601 timestamp. Return only entities whose created_at is greater than or equal to this value. | |
| exclude_bookkeeping | No | When true, omit chat bookkeeping types (`conversation`, `conversation_message`, etc.) from results. Default false. Has no effect when `entity_type` already filters to a bookkeeping type. | |
| snapshot_filters | No | Filter entities by snapshot field values. Each key is a snake_case snapshot field name (e.g. `status`, `priority`); the value specifies operator and comparison value. Filters are applied server-side via `snapshot->>{field}` JSONB extraction, so only entities whose snapshot contains a matching value are returned. Example: `{ "status": { "op": "eq", "value": "active" } }` returns only entities with `snapshot.status === "active"`. Supported ops: `eq`, `in`, `gt`, `lt`, `gte`, `lte`, `contains`. |