---
title: "listEntities"
method: POST
path: "/v1/entity:list"
tags: ["Entities"]
---

# listEntities

`POST /v1/entity:list`

List entities that meet the specified conditions.

Supports the same options as entity search but utilizes filtering using a subset of [Elastic Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) and does not perform scoring.

## Request body

- EntityListParams
  - `query` object — Query configuration object for searching entities
    - `query_string` object, required — Query string configuration based on Elasticsearch query_string query
      - `query` string, required — The actual query string using Lucene query syntax
      - `fields` string[] — List of fields to search in. If not provided, searches in default fields
      - `default_operator` 'AND' | 'OR' — The default boolean operator used if no explicit operator is specified
      - `lenient` boolean — If true, format-based errors are ignored
  - `filter` object[], required — A subset of simplified Elasticsearch query clauses. The default operator is a logical AND. Use nested $and, $or, $not to combine filters using different logical operators.
    - `term` object — Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization. You likely DO NOT want to use this filter on text fields and want to target its .keyword instead.
    - `terms` object — Returns documents that contain one of the exact terms in a provided field. See term filter for more info.
    - `ids` object — Returns documents based on their IDs.
      - `values` string[]
    - `range` object — Returns documents with fields that have terms within a certain range.
    - `exists` object — Returns documents that have a value in the specified field.
      - `field` string, required
    - `$and` SearchFilter — recursive
    - `$or` SearchFilter — recursive
    - `$not` SearchFilter — recursive
  - `allow_targeting_all_schemas` boolean — Allow running the listing without any schema filter. This is disabled by default to prevent security and performance issues if done by an accident.
  - `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.
  - `include_scores` boolean — Adds a `_score` number field to results that can be used to rank by match score
  - `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)