---
type: api
title: Create a new watchlist
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-createwatchlist
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-createwatchlist
products:
  - Kibana
---

# Create a new watchlist

Availability:

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

## Paths

- `POST` `/api/entity_analytics/watchlists`
- `POST` `/s/{space_id}/api/entity_analytics/watchlists`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)

## Description

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

`application/json`

- `description` (string · max: 1000) — optional
  Description of the watchlist
- `entitySources` ([] object · max: 100) — optional
  Optional entity sources to create and link to the watchlist
  - `enabled` (boolean) — optional
  - `filter` ({}) — optional
    - `kuery` (union oneOf) — optional
      One of: `string` or `object`
  - `identifierField` (string · max: 256) — optional
    Field used to query the entity store for index-type sources
  - `indexPattern` (string · max: 1000) — optional
  - `integrationName` (string · max: 256) — optional
    Required when type is entity_analytics_integration. One of entityanalytics_okta, entityanalytics_ad.
  - `matchers` ([] object · max: 100) — optional
    - `fields` ([] string · max: 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: 256) — required
  - `queryRule` (string · max: 4096) — optional
    KQL query used to filter data from the provided index patterns
  - `range` ({}) — optional
    Defines the lookback period for filtering source data by timestamp.
    - `end` (string · max: 256) — required
      End of the lookback period (date math or ISO string, e.g. "now")
    - `start` (string · max: 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: 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)
  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)
  Timestamp indicating when the watchlist was last updated
- `entitySources` ([] object)
  - `enabled` (boolean)
  - `filter` ({})
    - `kuery` (union oneOf)
      One of: `string` or `object`
  - `identifierField` (string · max: 256)
    Field used to query the entity store for index-type sources
  - `indexPattern` (string · max: 1000)
  - `integrationName` (string · max: 256)
  - `integrations` ({})
    - `syncData` (object)
      integrations latest full sync and update syncData
      - `lastFullSync` (string)
        Timestamp of the last full sync from integrations
      - `lastUpdateProcessed` (string)
        Timestamp of the last update processed from integrations
    - `syncMarkerIndex` (string · max: 1000)
      Index to read latest sync markers from
  - `matchers` ([] object · max: 100)
    - `fields` ([] string · max: 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: 256)
  - `queryRule` (string · max: 4096)
    KQL query used to filter data from the provided index patterns
  - `range` ({})
    Defines the lookback period for filtering source data by timestamp.
    - `end` (string · max: 256)
      End of the lookback period (date math or ISO string, e.g. "now")
    - `start` (string · max: 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: 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 /api/entity_analytics/watchlists
{
  "description": "High risk vendor watchlist",
  "managed": false,
  "name": "High Risk Vendors",
  "riskModifier": 1.5
}
```

#### curl

```curl
curl -X POST "https://{kibana_url}/api/entity_analytics/watchlists" \
  -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"
}
```