Elasticsearch API

Base URL 
http://api.example.com

Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.

Documentation source and versions

This documentation is derived from the 8.x branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International. This documentation contains work-in-progress information for future Elastic Stack releases.

Last update on Aug 28, 2025.

This API is provided under license Apache 2.0.

Get aliases Generally available

GET /_cat/aliases/{name}
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/aliases

GET /_cat/aliases/{name}

Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.

Required authorization

  • Index privileges: view_index_metadata

Path parameters

  • name string | array[string]

    A comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.

Query parameters

  • h string | array[string]

    List of columns to appear in the response. Supports simple wildcards.

  • s string | array[string]

    List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

  • expand_wildcards string | array[string]

    The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.

    Supported values include:

    • all: Match any data stream or index, including hidden ones.
    • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
    • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
    • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
    • none: Wildcard expressions are not accepted.

    Values are all, open, closed, hidden, or none.

  • local boolean

    If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • alias string

      alias name

    • index string
    • filter string

      filter

    • routing.index string

      index routing

    • routing.search string

      search routing

    • is_write_index string

      write index
GET /_cat/aliases/{name} 
GET _cat/aliases?format=json&v=true

resp = client.cat.aliases(
    format="json",
    v=True,
)
const response = await client.cat.aliases({
  format: "json",
  v: "true",
});
response = client.cat.aliases(
  format: "json",
  v: "true"
)
$resp = $client->cat()->aliases([
    "format" => "json",
    "v" => "true",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/aliases?format=json&v=true"
client.cat().aliases();
Response examples (200)
A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations. 
[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]

Update the connector error field Technical preview; Added in 8.12.0

PUT /_connector/{connector_id}/_error
Api key auth Basic auth Bearer auth

Set the error field for the connector. If the error provided in the request body is non-null, the connector’s status is updated to error. Otherwise, if the error is reset to null, the connector status is updated to connected.

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • error string | null Required

    One of:
    string-1 string NullValue string | null

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result string Required

      Values are created, updated, deleted, not_found, or noop.
PUT /_connector/{connector_id}/_error 
PUT _connector/my-connector/_error
{
    "error": "Houston, we have a problem!"
}
resp = client.connector.update_error(
    connector_id="my-connector",
    error="Houston, we have a problem!",
)
const response = await client.connector.updateError({
  connector_id: "my-connector",
  error: "Houston, we have a problem!",
});
response = client.connector.update_error(
  connector_id: "my-connector",
  body: {
    "error": "Houston, we have a problem!"
  }
)
$resp = $client->connector()->updateError([
    "connector_id" => "my-connector",
    "body" => [
        "error" => "Houston, we have a problem!",
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"error":"Houston, we have a problem!"}' "$ELASTICSEARCH_URL/_connector/my-connector/_error"
client.connector().updateError(u -> u
    .connectorId("my-connector")
    .error("Houston, we have a problem!")
);
Request example 
{
    "error": "Houston, we have a problem!"
}
Response examples (200) 
{
  "result": "updated"
}

Delete the license Generally available

DELETE /_license
Api key auth Basic auth Bearer auth

When the license expires, your subscription level reverts to Basic.

If the operator privileges feature is enabled, only operator users can use this API.

Required authorization

  • Cluster privileges: manage
External documentation

Query parameters

  • master_timeout string

    The period to wait for a connection to the master node.

    Values are -1 or 0.

  • timeout string

    The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

    Values are -1 or 0.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.
DELETE /_license 
DELETE /_license

resp = client.license.delete()
const response = await client.license.delete();
response = client.license.delete
$resp = $client->license()->delete();
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_license"
client.license().delete(d -> d);

Delete a Logstash pipeline Generally available; Added in 7.12.0

DELETE /_logstash/pipeline/{id}
Api key auth Basic auth Bearer auth

Delete a pipeline that is used for Logstash Central Management. If the request succeeds, you receive an empty response with an appropriate status code.

Required authorization

  • Cluster privileges: manage_logstash_pipelines
External documentation

Path parameters

  • id string Required

    An identifier for the pipeline.

Responses

  • 200 application/json
DELETE /_logstash/pipeline/{id} 
DELETE _logstash/pipeline/my_pipeline

resp = client.logstash.delete_pipeline(
    id="my_pipeline",
)
const response = await client.logstash.deletePipeline({
  id: "my_pipeline",
});
response = client.logstash.delete_pipeline(
  id: "my_pipeline"
)
$resp = $client->logstash()->deletePipeline([
    "id" => "my_pipeline",
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_logstash/pipeline/my_pipeline"
client.logstash().deletePipeline(d -> d
    .id("my_pipeline")
);

Get anomaly detection job results for buckets Generally available; Added in 5.4.0

POST /_ml/anomaly_detectors/{job_id}/results/buckets/{timestamp}
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_ml/anomaly_detectors/{job_id}/results/buckets

POST /_ml/anomaly_detectors/{job_id}/results/buckets
GET /_ml/anomaly_detectors/{job_id}/results/buckets/{timestamp}
POST /_ml/anomaly_detectors/{job_id}/results/buckets/{timestamp}

The API presents a chronological view of the records, grouped by bucket.

Required authorization

  • Cluster privileges: monitor_ml

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

  • timestamp string | number Required

    The timestamp of a single bucket result. If you do not specify this parameter, the API returns information about all buckets.

Query parameters

  • anomaly_score number

    Returns buckets with anomaly scores greater or equal than this value.

  • desc boolean

    If true, the buckets are sorted in descending order.

  • end string | number

    Returns buckets with timestamps earlier than this time. -1 means it is unset and results are not limited to specific timestamps.

  • exclude_interim boolean

    If true, the output excludes interim results.

  • expand boolean

    If true, the output includes anomaly records.

  • from number

    Skips the specified number of buckets.

  • size number

    Specifies the maximum number of buckets to obtain.

  • sort string

    Specifies the sort field for the requested buckets.

  • start string | number

    Returns buckets with timestamps after this time. -1 means it is unset and results are not limited to specific timestamps.

application/json

Body

  • anomaly_score number

    Refer to the description for the anomaly_score query parameter.

    Default value is 0.

  • desc boolean

    Refer to the description for the desc query parameter.

    Default value is false.

  • end string | number

    A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

    One of:
    string-1 string UnitMillis number
  • exclude_interim boolean

    Refer to the description for the exclude_interim query parameter.

    Default value is false.

  • expand boolean

    Refer to the description for the expand query parameter.

    Default value is false.

  • page object
    Hide page attributes Show page attributes object
    • from number

      Skips the specified number of items.

      Default value is 0.

    • size number

      Specifies the maximum number of items to obtain.

      Default value is 10000.

  • sort string

    Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • start string | number

    A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

    One of:
    string-1 string UnitMillis number

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • buckets array[object] Required
      Hide buckets attributes Show buckets attributes object
      • anomaly_score number Required

        The maximum anomaly score, between 0-100, for any of the bucket influencers. This is an overall, rate-limited score for the job. All the anomaly records in the bucket contribute to this score. This value might be updated as new data is analyzed.

      • bucket_influencers array[object] Required
        Hide bucket_influencers attributes Show bucket_influencers attributes object
        • anomaly_score number Required

          A normalized score between 0-100, which is calculated for each bucket influencer. This score might be updated as newer data is analyzed.

        • bucket_span number

          Time unit for seconds

        • influencer_field_name string Required

          Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • initial_anomaly_score number Required

          The score between 0-100 for each bucket influencer. This score is the initial value that was calculated at the time the bucket was processed.

        • is_interim boolean Required

          If true, this is an interim result. In other words, the results are calculated based on partial input data.

        • job_id string Required
        • probability number Required

          The probability that the bucket has this behavior, in the range 0 to 1. This value can be held to a high precision of over 300 decimal places, so the anomaly_score is provided as a human-readable and friendly interpretation of this.

        • raw_anomaly_score number Required

          Internal.

        • result_type string Required

          Internal. This value is always set to bucket_influencer.

        • timestamp number

          Time unit for milliseconds

        • timestamp_string string
      • bucket_span number

        Time unit for seconds

      • event_count number Required

        The number of input data records processed in this bucket.

      • initial_anomaly_score number Required

        The maximum anomaly score for any of the bucket influencers. This is the initial value that was calculated at the time the bucket was processed.

      • is_interim boolean Required

        If true, this is an interim result. In other words, the results are calculated based on partial input data.

      • job_id string Required
      • processing_time_ms number

        Time unit for milliseconds

      • result_type string Required

        Internal. This value is always set to bucket.

      • timestamp number

        Time unit for milliseconds

      • timestamp_string string | number

        A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

        One of:
        string-1 string UnitMillis number
    • count number Required
POST /_ml/anomaly_detectors/{job_id}/results/buckets/{timestamp} 
GET _ml/anomaly_detectors/low_request_rate/results/buckets
{
  "anomaly_score": 80,
  "start": "1454530200001"
}
resp = client.ml.get_buckets(
    job_id="low_request_rate",
    anomaly_score=80,
    start="1454530200001",
)
const response = await client.ml.getBuckets({
  job_id: "low_request_rate",
  anomaly_score: 80,
  start: 1454530200001,
});
response = client.ml.get_buckets(
  job_id: "low_request_rate",
  body: {
    "anomaly_score": 80,
    "start": "1454530200001"
  }
)
$resp = $client->ml()->getBuckets([
    "job_id" => "low_request_rate",
    "body" => [
        "anomaly_score" => 80,
        "start" => "1454530200001",
    ],
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"anomaly_score":80,"start":"1454530200001"}' "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/results/buckets"
client.ml().getBuckets(g -> g
    .anomalyScore(80.0D)
    .jobId("low_request_rate")
    .start(DateTime.of("1454530200001"))
);
Request example
An example body for a `GET _ml/anomaly_detectors/low_request_rate/results/buckets` request. 
{
  "anomaly_score": 80,
  "start": "1454530200001"
}