v5

latestOpenAPI 3.0.22026-08-0688147257.1 KB

Entities

listEntities

List entities that meet the specified conditions.

Supports the same options as entity search but utilizes filtering using a subset of Elastic Query DSL and does not perform scoring.

post/v1/entity:list

Request body

allow_targeting_all_schemasboolean

Allow running the listing without any schema filter. This is disabled by default to prevent security and performance issues if done by an accident.

frominteger

The offset from which to start the search results. Only one of from or search_after should be used.

sizeinteger

Max search size is 1000 with higher values defaulting to 1000

hydrateboolean

When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.

anonymizeboolean

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.

fieldsstring[]

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.

aggsobject

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_scoresboolean

Adds a _score number field to results that can be used to rank by match score

{"stackTrail":"components:schemas:EntityListParams:allOf:properties:highlight","oasType":"schema","type":"unknown"}

stable_forinteger

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_idstring

A unique identifier of the query context from the last stable query. The context is maintained for the duration of the stable_for value.

Example request

{
  "query": {
    "query_string": {
      "query": "status:active",
      "fields": [
        "_title",
        "_tags",
        "status"
      ]
    }
  },
  "filter": [
    {
      "term": {
        "_schema": "contact"
      }
    },
    {
      "terms": {
        "status": [
          "active"
        ]
      }
    }
  ],
  "fields": [
    "_id",
    "_title",
    "first_name",
    "account",
    "!account.*._files",
    "**._product"
  ],
  "aggs": {
    "contact-count-per-tag": {
      "terms": {
        "field": "_tags.keyword"
      }
    }
  }
}

Response

Success

hitsnumber

aggregationsobject

stable_query_idstring

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.

Example response

{
  "hits": 1,
  "results": [
    {
      "_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "_org": "123",
      "_owners": [
        {
          "org_id": "123",
          "user_id": "123"
        }
      ],
      "_schema": "contact",
      "_tags": [
        "example",
        "mock"
      ],
      "_created_at": "2021-02-09T12:41:43.662Z",
      "_updated_at": "2021-02-09T12:41:43.662Z",
      "_acl": {
        "view": [
          "org:456",
          "org:789"
        ],
        "edit": [
          "org:456"
        ],
        "delete": [
          "org:456"
        ]
      },
      "_manifest": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "aggregations": {
    "contact-count-per-tag": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 23,
      "buckets": [
        {
          "key": "automation",
          "doc_count": 108
        },
        {
          "key": "primary",
          "doc_count": 66
        }
      ]
    }
  },
  "sort_end": [
    1747905443332,
    "0.000023312468"
  ]
}