---
type: api
title: Create a new watchlist
description: Creates a new entity analytics watchlist with an optional set of entity sources. Watchlists apply a risk score modifier to matched entities.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana/v0/operation/operation-createwatchlist
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana/v0/operation/operation-createwatchlist
products:
  - Kibana
---

# Create a new watchlist

Availability: Preview

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/entity_analytics/watchlists`

## Description

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

## Authentication

- Api key: `Authorization: <value>`
  These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
- Basic: `Authorization: Basic <credentials>`

## Request body

`application/json`

- `description` (string · max length: 1000) — optional
  Description of the watchlist
- `entitySources` (object[] · max items: 100) — optional
  Optional entity sources to create and link to the watchlist
  - `enabled` (boolean) — optional
  - `filter` (object) — optional
    - `kuery` (union oneOf) — optional
      One of: `string` or `object`
  - `identifierField` (string · max length: 256) — optional
    Field used to query the entity store for index-type sources
  - `indexPattern` (string · max length: 1000) — optional
  - `integrationName` (string · max length: 256) — optional
    Required when type is entity_analytics_integration. One of entityanalytics_okta, entityanalytics_ad.
  - `matchers` (object[] · max items: 100) — optional
    - `fields` (string[] · max items: 100) — required
    - `values` (union string[] | boolean[]) — 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.
  - `name` (string · max length: 256) — required
  - `queryRule` (string · max length: 4096) — optional
    KQL query used to filter data from the provided index patterns
  - `range` (object) — optional
    Defines the lookback period for filtering source data by timestamp.
    - `end` (string · max length: 256) — required
      End of the lookback period (date math or ISO string, e.g. "now")
    - `start` (string · max length: 256) — required
      Start of the lookback period (date math or ISO string, e.g. "now-10d")
  - `type` (enum) — required
    Values: `index`, `entity_analytics_integration`, `store`
- `managed` (boolean) — optional
  Indicates if the watchlist is managed by the system
- `name` (string · max length: 256) — required
  Unique name for the watchlist
- `riskModifier` (number · min: 0 · max: 2) — required
  Risk score modifier associated with the watchlist

## Response

Watchlist created successfully

`application/json`

- `createdAt` (string · format: 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)
  Indicates if the watchlist is managed by the system
- `name` (string)
  The name of the watchlist
- `riskModifier` (number)
  Risk score modifier associated with the watchlist
- `updatedAt` (string · format: date-time)
  Timestamp indicating when the watchlist was last updated
- `entitySources` (object[])
  - `enabled` (boolean)
  - `filter` (object)
    - `kuery` (union oneOf)
      One of: `string` or `object`
  - `identifierField` (string · max length: 256)
    Field used to query the entity store for index-type sources
  - `indexPattern` (string · max length: 1000)
  - `integrationName` (string · max length: 256)
  - `integrations` (object)
    - `syncData` (object)
      integrations latest full sync and update syncData
      - `lastFullSync` (string · format: date-time)
        Timestamp of the last full sync from integrations
      - `lastUpdateProcessed` (string · format: date-time)
        Timestamp of the last update processed from integrations
    - `syncMarkerIndex` (string · max length: 1000)
      Index to read latest sync markers from
  - `matchers` (object[] · max items: 100)
    - `fields` (string[] · max items: 100)
    - `values` (union string[] | boolean[])
      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.
  - `name` (string · max length: 256)
  - `queryRule` (string · max length: 4096)
    KQL query used to filter data from the provided index patterns
  - `range` (object)
    Defines the lookback period for filtering source data by timestamp.
    - `end` (string · max length: 256)
      End of the lookback period (date math or ISO string, e.g. "now")
    - `start` (string · max length: 256)
      Start of the lookback period (date math or ISO string, e.g. "now-10d")
  - `type` (enum)
    Values: `index`, `entity_analytics_integration`, `store`
  - `managed` (boolean)
  - `apiKeyId` (string · max length: 64) — nullable
    ID of the API key used for scoped reads from the source index. Only present for index-type sources.
  - `id` (string)
## Code examples

#### Console

```console
POST kbn:/api/entity_analytics/watchlists
{
  "description": "High risk vendor watchlist",
  "managed": false,
  "name": "High Risk Vendors",
  "riskModifier": 1.5
}
```

#### curl

```curl
curl -X POST "${KIBANA_URL}/api/entity_analytics/watchlists" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "High risk vendor watchlist",
    "managed": false,
    "name": "High Risk Vendors",
    "riskModifier": 1.5
  }'
```

## Response examples

#### Created watchlist

```json
{
  "createdAt": "2026-01-28T12:00:00.000Z",
  "description": "High risk vendor watchlist",
  "id": "watchlist-123",
  "managed": false,
  "name": "High Risk Vendors",
  "riskModifier": 1.5,
  "updatedAt": "2026-01-28T12:00:00.000Z"
}
```