---
title: External Elasticsearch connector
description: Use the External Elasticsearch connector to search and explore data on a remote cluster, retrieve mappings and aliases, and run ES|QL queries.
url: https://docs-v3-preview.elastic.dev/elastic/kibana/tree/main/reference/connectors-kibana/elasticsearch-action-type
products:
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Planned
---

# External Elasticsearch connector
The External Elasticsearch connector calls the [Elasticsearch REST API](https://www.elastic.co/docs/api/doc/elasticsearch) on a remote cluster so an agent can search and explore data, inspect index mappings and aliases, run ES|QL analytics queries, and retrieve cluster information. Use this connector when you need to query data on a separate Elasticsearch cluster — for example, a different Elastic Cloud deployment, a serverless project, an on-prem cluster behind a firewall, or any other cluster that is not directly accessible via cross-cluster search (CCS). The connector can be created from any Kibana deployment (including serverless) and can connect to any Elasticsearch cluster endpoint, whether Elastic Cloud, serverless, or self-managed.
<note>
  This connector is currently available in **Agent Builder** only. Workflow support is planned for a future release.
</note>


## Create connectors in Kibana

You can create connectors in **Stack Management > Connectors**.

### Connector configuration

Elasticsearch connectors have the following configuration properties:
<definitions>
  <definition term="Elasticsearch URL">
    The cluster endpoint URL. For Elastic Cloud, use the Elasticsearch endpoint shown in your deployment in the Elastic Cloud console (for example, `https://my-deployment.es.us-east-1.aws.elastic.cloud`). For self-managed clusters, use the full URL including port, for example `https://elasticsearch.example.com:9200`.
  </definition>
</definitions>


### Authentication

**Elasticsearch API key (recommended)**
<definitions>
  <definition term="API Key">
    The encoded API key value, in the form `ApiKey <encoded>` where `<encoded>` is the base64-encoded `id:api_key` string from the [create API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) response (`POST /_security/api_key`). Grant the key at minimum: `read` privilege on the indices you search.
  </definition>
</definitions>

**Username and password**
<definitions>
  <definition term="Username">
    An Elasticsearch user with at minimum `read` privilege on the indices you search.
  </definition>
  <definition term="Password">
    The password for that user.
  </definition>
</definitions>


## Test connectors

You can test connectors when you create or edit the connector in Kibana. The test calls `GET /` to verify connectivity and return cluster name and version information.

## Connector actions

The Elasticsearch connector has the following actions:
<definitions>
  <definition term="search">
    Search documents in one or more indices using the [Elasticsearch Query DSL](https://www.elastic.co/docs/reference/query-languages/querydsl). Pass the full query body in the `query` parameter. Supports aggregations (`aggs`), sorting, field filtering (`_source`), and pagination (`size`, `from`). Use `listIndices` first if you do not know the index name, and `getMapping` to understand the available fields.
  </definition>
  <definition term="esql">
    Run an [ES|QL](https://www.elastic.co/docs/reference/query-languages/esql) query — a pipe-based analytics language optimized for time-series exploration and aggregations. Returns a columnar result set with column names and row values. Requires Elasticsearch 8.11 or later.
  </definition>
  <definition term="listIndices">
    List indices and data streams with their health, status, document count, and storage size. Optionally filter by name pattern (for example, `logs-*`). Use this to discover available indices before calling `search`, `getMapping`, or `esql`.
  </definition>
  <definition term="getMapping">
    Retrieve the field mapping for an index: field names, types, and configured analyzers or sub-fields. Use this to understand which fields are available before constructing a query.
  </definition>
  <definition term="request">
    Make an arbitrary `GET` request to any Elasticsearch REST API path. Use this as an escape hatch when no typed action covers the endpoint you need — for example, `GET /_cluster/health`, `GET /_alias`, or `GET /_nodes`. The base cluster URL is prepended automatically.
  </definition>
  <definition term="getClusterInfo">
    Get basic information about the cluster: name, version, and build. To check shard/node counts and cluster status, use the `request` action with path `/_cluster/health`.
  </definition>
</definitions>


## Get API credentials

**Elasticsearch API key**
1. Log in to Kibana and go to **Stack Management > API Keys**.
2. Click **Create API key**.
3. Give the key a name and, under **Control security privileges**, grant at minimum:
   - `read` indices privilege on the index patterns you intend to search.
4. Click **Create API key**, then copy the **Encoded** value.
5. Enter the Elasticsearch endpoint URL and the encoded key (prefixed with `ApiKey `, for example `ApiKey dGhpcyBpcyBhIHRlc3Q=`) when configuring the connector in Kibana.

Alternatively, create the key via the API:
```json

{
  "name": "kibana-elasticsearch-connector",
  "role_descriptors": {
    "connector-role": {
      "cluster": [],
      "indices": [
        {
          "names": ["logs-*", "metrics-*"],
          "privileges": ["read"]
        }
      ]
    }
  }
}
```

Use the `encoded` field from the response as the **API Key** value, prepended with `ApiKey `.
**Username and password (self-managed clusters)**
1. Create a dedicated Elasticsearch user (for example, using the [Create or update users API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-user)).
2. Assign a role granting at minimum `read` on the indices you search.
3. Enter the cluster URL, username, and password when configuring the connector in Kibana.