---
title: "Create a new watchlist"
method: POST
path: "/api/entity_analytics/watchlists"
tags: ["Security Entity Analytics API"]
---

# Create a new watchlist

`POST /api/entity_analytics/watchlists`

**Spaces method and path for this operation:**

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/entity_analytics/watchlists</span></div>

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Creates a new entity analytics watchlist with an optional set of entity sources. Watchlists apply a risk score modifier to matched entities.

## Request body

- object
  - `description` string — Description of the watchlist
  - `entitySources` object[] — Optional entity sources to create and link to the watchlist
    - `enabled` boolean
    - `filter` SecurityEntityAnalyticsAPIFilter
      - `kuery` union
        - string
        - object
    - `identifierField` string — Field used to query the entity store for index-type sources
    - `indexPattern` string
    - `integrationName` string — Required when type is entity_analytics_integration. One of entityanalytics_okta, entityanalytics_ad.
    - `matchers` SecurityEntityAnalyticsAPIMatcher[]
      - `fields` string[], required
      - `values` union, required — Matcher values. Must be either an array of strings (e.g. group or role names) or an array of booleans (e.g. integration-derived flags like privileged_group_member). Mixed types are intentionally not supported for simplicity and predictability.
        - string[]
        - boolean[]
    - `name` string, required
    - `queryRule` string — KQL query used to filter data from the provided index patterns
    - `range` SecurityEntityAnalyticsAPIDateRange — Defines the lookback period for filtering source data by timestamp.
      - `end` string, required — End of the lookback period (date math or ISO string, e.g. "now")
      - `start` string, required — Start of the lookback period (date math or ISO string, e.g. "now-10d")
    - `type` 'index' | 'entity_analytics_integration' | 'store', required
  - `managed` boolean — Indicates if the watchlist is managed by the system
  - `name` string, required — Unique name for the watchlist
  - `riskModifier` number, required — Risk score modifier associated with the watchlist

## Response `200`

Watchlist created successfully

- object
  - `createdAt` string, date-time — Timestamp indicating when the watchlist was created
  - `description` string — Description of the watchlist
  - `entityCount` number — Number of entities in the watchlist
  - `entitySourceIds` string[] — List of entity source IDs associated with the watchlist
  - `hasManualEntities` boolean — Indicates whether the watchlist contains manually assigned entities
  - `id` string — The unique ID of the watchlist
  - `managed` boolean, required — Indicates if the watchlist is managed by the system
  - `name` string, required — The name of the watchlist
  - `riskModifier` number, required — Risk score modifier associated with the watchlist
  - `updatedAt` string, date-time — Timestamp indicating when the watchlist was last updated
  - `entitySources` SecurityEntityAnalyticsAPIMonitoringEntitySource[]
    - `enabled` boolean
    - `filter` SecurityEntityAnalyticsAPIFilter
      - `kuery` union
        - string
        - object
    - `identifierField` string — Field used to query the entity store for index-type sources
    - `indexPattern` string
    - `integrationName` string
    - `integrations` SecurityEntityAnalyticsAPIIntegrations
      - `syncData` object — integrations latest full sync and update syncData
        - `lastFullSync` string, date-time — Timestamp of the last full sync from integrations
        - `lastUpdateProcessed` string, date-time — Timestamp of the last update processed from integrations
      - `syncMarkerIndex` string — Index to read latest sync markers from
    - `matchers` SecurityEntityAnalyticsAPIMatcher[]
      - `fields` string[], required
      - `values` union, required — Matcher values. Must be either an array of strings (e.g. group or role names) or an array of booleans (e.g. integration-derived flags like privileged_group_member). Mixed types are intentionally not supported for simplicity and predictability.
        - string[]
        - boolean[]
    - `name` string, required
    - `queryRule` string — KQL query used to filter data from the provided index patterns
    - `range` SecurityEntityAnalyticsAPIDateRange — Defines the lookback period for filtering source data by timestamp.
      - `end` string, required — End of the lookback period (date math or ISO string, e.g. "now")
      - `start` string, required — Start of the lookback period (date math or ISO string, e.g. "now-10d")
    - `type` 'index' | 'entity_analytics_integration' | 'store', required
    - `managed` boolean, required
    - `apiKeyId` string, nullable — ID of the API key used for scoped reads from the source index. Only present for index-type sources.
    - `id` string, required

---

[API](https://skmtc.net/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.net/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/kibana-apis/versions/531c9e2a7d23/schema)