---
type: api
title: Upload a CSV file to add entities to a watchlist
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-uploadwatchlistcsv
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-uploadwatchlistcsv
products:
  - Kibana
---

# Upload a CSV file to add entities to a watchlist

Availability:

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

## Paths

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

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

#### Path Parameters

- `watchlist_id` (string)
  The ID of the watchlist to add entities to

## Description

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

Uploads a CSV file to add entities to a watchlist. The CSV must contain a header row
with a "type" column (user, host, service, or generic) and one or more ECS identity
fields (e.g. "user.name", "host.hostname") used to match entities in the entity store.

Matched entities are added to the watchlist and their `entity.attributes.watchlists`
field is updated in the entity store.

Each row will match up to 10,000 entities.

## Request Body

`multipart/form-data`

- `file` (string) — required
  The CSV file to upload.

## Responses

#### `200`

Upload successful

`application/json`

- `failed` (integer)
  Number of rows that failed to process
- `items` ([] object)
  - `error` (string)
    Error message if the row failed to process
  - `matchedEntities` (integer)
    Number of entities matched for this row
  - `status` (enum)
    Values: `success`, `failure`, `unmatched`
- `successful` (integer)
  Number of rows that matched at least one entity
- `total` (integer)
  Total number of rows processed
- `unmatched` (integer)
  Number of rows that matched no entities
#### `413`

File too large

## Code Examples

#### Console

```console
POST /api/entity_analytics/watchlists/{watchlist_id}/csv_upload
{
  "file": "type,user.name\nuser,john.doe\nuser,jane.smith\n"
}
```

#### curl

```curl
curl -X POST "https://{kibana_url}/api/entity_analytics/watchlists/{watchlist_id}/csv_upload" \
  -H "Content-Type: multipart/form-data" \
  -d '{
  "file": "type,user.name\nuser,john.doe\nuser,jane.smith\n"
}'
```

## Response Examples

#### CSV upload response with mixed results

```json
{
  "failed": 1,
  "items": [
    {
      "matchedEntities": 1,
      "status": "success"
    },
    {
      "error": "Invalid entity type",
      "matchedEntities": 0,
      "status": "failure"
    },
    {
      "matchedEntities": 0,
      "status": "unmatched"
    }
  ],
  "successful": 1,
  "total": 3,
  "unmatched": 1
}
```