retrieve_entities
Fetch entities from Neotoma with filters for type, search, dates, and publication status. Supports efficient cursor pagination for large result sets.
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. For deep pagination under the default sort (sort_by=entity_id), pass the next_cursor from a prior response back as cursor instead of a large offset; offset beyond a bounded depth is rejected and cursor is not supported with search, non-default sort_by, or a non-zero offset in the same call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entities to return (default 100). Capped at 500 when `include_snapshots` is true (the default), since each snapshot is hydrated synchronously; lower the page size or set `include_snapshots=false` for larger pages. | |
| query | No | Compatibility alias for `search`. | |
| cursor | No | Opaque keyset pagination cursor from a previous response's `next_cursor`. Returns the next page in O(page size) time regardless of position, unlike `offset` which is bounded and deprecated. Only supported with the default `sort_by=entity_id`; cannot be combined with `search` or a non-zero `offset`. Reusing a cursor after changing `sort_order` returns a structured error. | |
| offset | No | Deprecated in favor of `cursor`. Still accepted for back-compat but internally bounded: values above 2000 are rejected with a structured hint pointing to `cursor`. Supplying a non-zero `offset` together with `cursor` is rejected as a validation error; use one or the other. (default 0). | |
| search | No | Canonical free-text query for lexical/semantic retrieval. Cannot be combined with published filters or non-default sorting. | |
| 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. | |
| user_id | No | Optional explicit user ID (normally inferred from auth context). | |
| published | No | Filter by snapshot.published. Cannot be combined with `search`. | |
| sort_order | No | Sort direction. `desc` cannot be combined with `search`. | |
| 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_query | No | Compatibility alias for `search`. | |
| created_since | No | ISO 8601 timestamp. Return only entities whose created_at is greater than or equal to this value. | |
| updated_since | No | ISO 8601 timestamp. Return only entities whose updated_at is greater than or equal to this value. | |
| include_merged | No | Whether to include merged entities (default false). | |
| 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`. | |
| 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`, `contains_word`. `contains` is a raw case-insensitive SUBSTRING match — `{ "title": { "op": "contains", "value": "CTO" } }` also matches "director" and "doctor", and `"COO"` matches "coordinator". Prefer `contains_word` when you mean a whole word/token: it matches only when the value appears as a complete token delimited by punctuation or whitespace, so `"CTO"` matches "VP, CTO" and "CTO & Co-founder" but not "director"; `"Care"` does not match "Careers". Punctuation inside the term is handled: `"O'Brien"`, `"R&D"`, and `"100%"` match their stored values (separators in the term are normalized the same way as the stored value). Case-insensitivity for `contains_word` is ASCII-only. | |
| include_snapshots | No | When false, omit snapshot/provenance/raw_fragments payloads for lightweight responses. | |
| 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. | |
| similarity_threshold | No | Semantic distance threshold when `search` is used. Lower is stricter (typical 1.0-1.05). |