---
title: "searchEntities"
method: POST
path: "/v1/entity:search"
tags: ["Entities"]
---

# searchEntities

`POST /v1/entity:search`

Search for entities. Supports ordering and pagination. [Lucene query syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax) supported for complex querying.

Passing comma-separated `x-epilot-org-id` is supported for cross-org entity search.

## Relations

When `hydrate=true`, relation attributes are replaced in-place with nested entity values.

Example:
```json
{
  "_id": "123",
  "name": "parent",
  "_tags": ["parent"],
  "contacts": {
    "$relation": [
      { "entity_id": "456", "_tags": ["primary"] },
      { "entity_id": "789", "_tags": ["secondary"] },
    ]
  },
  "addresses": {
    "$relation_ref": [
      { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
      { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
    ]
  }
}
```

Becomes:
```json
{
  "_id": "123",
  "name": "parent",
  "_tags": ["parent"],
  "contacts": [
    {
      "$relation": { "entity_id": "456", "_tags": ["primary"] },
      "_id": "456",
      "name": "child 1",
      "_tags": ["child"]
    },
    {
      "$relation": { "entity_id": "789", "_tags": ["secondary"] },
      "_id": "789",
      "name": "child 2",
      "_tags": ["child"]
    }
  ],
  "addresses": [
    {
      "$relation_ref": { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
      "_id": "123",
      "address": "address 1",
      "_tags": ["child"]
    },
    {
      "$relation_ref": { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
      "_id": "234",
      "address": "address 2",
      "_tags": ["child"]
    }
  ]
}
```

## Request body

- EntitySearchParams
  - `q` string, required — Lucene [queries supported with ElasticSearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)
  - `include_scores` boolean — Adds a `_score` number field to results that can be used to rank by match score
  - `sort` union
    - string
    - string[]
  - `from` integer — The offset from which to start the search results. Only one of `from` or `search_after` should be used.
  - `size` integer — Max search size is 1000 with higher values defaulting to 1000
  - `hydrate` boolean — When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.
  - `anonymize` boolean — When true, anonymizes PII in the response: identifiers are replaced with deterministic pseudonyms, addresses are generalized and well-known free-text fields are redacted. Anonymization is forced (regardless of this parameter) when the access token was created with `anonymize: true`.
  - `fields` string[] — List of entity fields to include or exclude in the response Use ! to exclude fields, e.g. `!_id` to exclude the `_id` field. Globbing and globstart (**) is supported for nested fields.
  - `aggs` object — Aggregation supported by ElasticSearch allows summarizing data as metrics, statistics, or other analytics.
  - `include_deleted` 'true' | 'false' | 'only' — Whether to include deleted entities in the search results - `true`: include deleted entities - `false`: exclude deleted entities - `only`: include only deleted entities By default, no deleted entities are included in the search results.
  - `highlight` unknown
  - `stable_for` integer — A TTL (in seconds) that specifies how long the context should be maintained. Defaults to 30 seconds; configurable up to 60 seconds to prevent abuse. A value of 0 can be provided the close the context after the query. Defaults to none.
  - `stable_query_id` string — A unique identifier of the query context from the last stable query. The context is maintained for the duration of the stable_for value.
  - `search_after` union[] — The sort values from which to start the search results. Only one of `from` or `search_after` should be used. It is strongly recommended to always use the `sort_end` field from the last search result. Used for deep pagination, typically together with `stable_query_id` to maintain the context between requests. Requires explicit sort to work reliably. Typically used sort fields are `_id` or `_created_at`.
    - union
      - string, nullable
      - number, nullable

## Response `200`

Success

- EntitySearchResults
  - `hits` number
  - `results` EntityItem[]
    - `_id` string, uuid, required
    - `_org` string, required — Organization Id the entity belongs to
    - `_owners` EntityOwner[]
      - `org_id` string, required
      - `user_id` string
    - `_schema` string, required — URL-friendly identifier for the entity schema
    - `_title` string, nullable, required — Title of entity
    - `_tags` string[], nullable
    - `_created_at` string, date-time, nullable, required
    - `_updated_at` string, date-time, nullable, required
    - `_deleted_at` string, date-time, nullable
    - `_acl` object — Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
      - `view` string[]
      - `edit` string[]
      - `delete` string[]
    - `_purpose` string[], nullable
    - `_purpose_name` string[], nullable — Automatically computed purpose names from _purpose attribute
    - `_manifest` string[], nullable — Manifest ID used to create/update the entity
    - `_changesets` object, nullable — Pending attribute changesets for attributes configured with external or approval edit mode. The value shape is `Changeset` (`proposed_value`, `created_at`, `edit_mode`, ...) and is what `:apply` / `:dismiss` operate on. Read-only via normal entity PATCH/PUT operations — those handlers strip `_changesets` from request bodies. Use the changeset management endpoints to mutate this field.
  - `aggregations` object
  - `stable_query_id` string — A unique identifier of the query context. Should be used on the input for the next query that needs to be executed in the same context.
  - `sort_end` union[] — The sort value of the last item returned in `results`. Can be used as the input for the `search_after` in the next query.
    - union
      - string, nullable
      - number, nullable

## Other responses

- `429` — Too many requests

---

[API](https://skmtc.net/epilot/apis/entity-api.md) · [All operations](https://skmtc.net/epilot/apis/entity-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/entity-api/versions/8dd3d44e1c4f/schema)