retrieve_entities
Retrieve filtered entity lists by type, pagination, and date filters, or perform lexical/semantic search across versioned entities.
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. Compatibility aliases search_query and query are accepted but search is canonical.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | Optional entity type filter (for example: post, task, contact). | |
| 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`. | |
| 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. |