Compact and aligned text (CAT)

The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, it's recommend to use a corresponding JSON API. All the cat commands accept a query string parameter help to see all the headers and info they provide, and the /_cat command alone lists all the available commands.

Get aliases Generally available

GET /_cat/aliases/{name}

Api key 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]
A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:
- alias (or a): The name of the alias.
- index (or i, idx): The name of the index the alias points to.
- filter (or f, fi): The filter applied to the alias.
- routing.index (or ri, routingIndex): Index routing value for the alias.
- routing.search (or rs, routingSearch): Search routing value for the alias.
- is_write_index (or w, isWriteIndex): Indicates if the index is the write index for the alias.
Values are alias, a, index, i, idx, filter, f, fi, routing.index, ri, routingIndex, routing.search, rs, routingSearch, is_write_index, w, or isWriteIndex.
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.
master_timeout string

The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicated that the request should never timeout, you can set it to -1.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- alias string
  
  alias name
- index string
  
  index alias points to
- 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"
  }
]

Get component templates Generally available

GET /_cat/component_templates/{name}

Api key auth

All methods and paths for this operation:

GET /_cat/component_templates

GET /_cat/component_templates/{name}

Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

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

Required authorization

Cluster privileges: monitor

Path parameters

name string Required

The name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.

Query parameters

h string | array[string]
A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:
- name (or n): The name of the component template.
- version (or v): The version number of the component template.
- alias_count (or a): The number of aliases in the component template.
- mapping_count (or m): The number of mappings in the component template.
- settings_count (or s): The number of settings in the component template.
- metadata_count (or me): The number of metadata entries in the component template.
- included_in (or i): The index templates that include this component template.
Values are name, n, version, v, alias_count, a, mapping_count, m, settings_count, s, metadata_count, me, included_in, or i.
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.
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.
master_timeout string

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

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string Required
- version string | null Required
  
  One of:
  string-1 string string-2 string | null
- alias_count string Required
- mapping_count string Required
- settings_count string Required
- metadata_count string Required
- included_in string Required

GET /_cat/component_templates/{name}

GET _cat/component_templates/my-template-*?v=true&s=name&format=json

resp = client.cat.component_templates(
    name="my-template-*",
    v=True,
    s="name",
    format="json",
)

const response = await client.cat.componentTemplates({
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json",
});

response = client.cat.component_templates(
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json"
)

$resp = $client->cat()->componentTemplates([
    "name" => "my-template-*",
    "v" => "true",
    "s" => "name",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/component_templates/my-template-*?v=true&s=name&format=json"

client.cat().componentTemplates();

Response examples (200)

A successful response from `GET _cat/component_templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "name": "my-template-1",
    "version": "null",
    "alias_count": "0",
    "mapping_count": "0",
    "settings_count": "1",
    "metadata_count": "0",
    "included_in": "[my-index-template]"
  },
    {
    "name": "my-template-2",
    "version": null,
    "alias_count": "0",
    "mapping_count": "3",
    "settings_count": "0",
    "metadata_count": "0",
    "included_in": "[my-index-template]"
  }
]

Get a document count Generally available

GET /_cat/count/{index}

Api key auth

All methods and paths for this operation:

GET /_cat/count

GET /_cat/count/{index}

Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.

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

Required authorization

Index privileges: read

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases used to limit the request. It supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Query parameters

h string | array[string]
A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:
- epoch (or t, time): The Unix epoch time in seconds since 1970-01-01 00:00:00.
- timestamp (or ts, hms, hhmmss): The current time in HH:MM:SS format.
- count (or dc, docs.count, docsCount): The document count in the cluster or index.
Values are epoch, t, time, timestamp, ts, hms, hhmmss, count, dc, docs.count, or docsCount.
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.

Responses

200 application/json
Hide response attributes Show response attributes object
- epoch number | string
  
  seconds since 1970-01-01 00:00:00
  
  One of:
  UnitSeconds number string-2 string
  
  seconds since 1970-01-01 00:00:00
- timestamp string
  
  time in HH:MM:SS
- count string
  
  the document count

GET /_cat/count/{index}

GET /_cat/count/my-index-000001?v=true&format=json

resp = client.cat.count(
    index="my-index-000001",
    v=True,
    format="json",
)

const response = await client.cat.count({
  index: "my-index-000001",
  v: "true",
  format: "json",
});

response = client.cat.count(
  index: "my-index-000001",
  v: "true",
  format: "json"
)

$resp = $client->cat()->count([
    "index" => "my-index-000001",
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/count/my-index-000001?v=true&format=json"

client.cat().count();

Response examples (200)

A successful response from `GET /_cat/count/my-index-000001?v=true&format=json`. It retrieves the document count for the `my-index-000001` data stream or index.

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "120"
  }
]

A successful response from `GET /_cat/count?v=true&format=json`. It retrieves the document count for all data streams and indices in the cluster.

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "121"
  }
]

Get CAT help Generally available

GET /_cat

Api key auth

Get help for the CAT APIs.

Responses

200 application/json

GET /_cat

curl \
 --request GET 'http://api.example.com/_cat' \
 --header "Authorization: $API_KEY"

Get datafeeds Generally available

GET /_cat/ml/datafeeds/{datafeed_id}

Api key auth

All methods and paths for this operation:

GET /_cat/ml/datafeeds

GET /_cat/ml/datafeeds/{datafeed_id}

Get configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API.

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

Required authorization

Cluster privileges: monitor_ml

Path parameters

datafeed_id string Required

A numerical character string that uniquely identifies the datafeed.

Query parameters

allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no datafeeds that match.
- Contains the _all string or no identifiers and there are no matches.
- Contains wildcard expressions and there are only partial matches.
If true, the API returns an empty datafeeds array when there are no matches and the subset of results when there are partial matches. If false, the API returns a 404 status code when there are no matches or only partial matches.
h string | array[string]
Comma-separated list of column names to display.

Supported values include:
- ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of a node.
- bc (or buckets.count, bucketsCount): The number of buckets processed.
- id: A numerical character string that uniquely identifies the datafeed.
- na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the datafeed is started.
- ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the datafeed is started.
- ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the datafeed is started.
- nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is started.
- sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.
- sc (or search.count, searchCount): The number of searches run by the datafeed.
- seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.
- st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.
- s (or state): The status of the datafeed: starting, started, stopping, or stopped. If starting, the datafeed has been requested to start but has not yet started. If started, the datafeed is actively receiving data. If stopping, the datafeed has been requested to stop gracefully and is completing its final action. If stopped, the datafeed is stopped and will not receive data until it is re-started.
s string | array[string]
Comma-separated list of column names or column aliases used to sort the response.

Supported values include:
- ae (or assignment_explanation): For started datafeeds only, contains messages relating to the selection of a node.
- bc (or buckets.count, bucketsCount): The number of buckets processed.
- id: A numerical character string that uniquely identifies the datafeed.
- na (or node.address, nodeAddress): For started datafeeds only, the network address of the node where the datafeed is started.
- ne (or node.ephemeral_id, nodeEphemeralId): For started datafeeds only, the ephemeral ID of the node where the datafeed is started.
- ni (or node.id, nodeId): For started datafeeds only, the unique identifier of the node where the datafeed is started.
- nn (or node.name, nodeName): For started datafeeds only, the name of the node where the datafeed is started.
- sba (or search.bucket_avg, searchBucketAvg): The average search time per bucket, in milliseconds.
- sc (or search.count, searchCount): The number of searches run by the datafeed.
- seah (or search.exp_avg_hour, searchExpAvgHour): The exponential average search time per hour, in milliseconds.
- st (or search.time, searchTime): The total time the datafeed spent searching, in milliseconds.
- s (or state): The status of the datafeed: starting, started, stopping, or stopped. If starting, the datafeed has been requested to start but has not yet started. If started, the datafeed is actively receiving data. If stopping, the datafeed has been requested to stop gracefully and is completing its final action. If stopped, the datafeed is stopped and will not receive data until it is re-started.
time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
  
  The datafeed identifier.
- state string
  
  The status of the datafeed.
  
  Values are started, stopped, starting, or stopping.
- assignment_explanation string
  
  For started datafeeds only, contains messages relating to the selection of a node.
- buckets.count string
  
  The number of buckets processed.
- search.count string
  
  The number of searches run by the datafeed.
- search.time string
  
  The total time the datafeed spent searching, in milliseconds.
- search.bucket_avg string
  
  The average search time per bucket, in milliseconds.
- search.exp_avg_hour string
  
  The exponential average search time per hour, in milliseconds.
- node.id string
  
  The unique identifier of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.
- node.name string
  
  The name of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.
- node.ephemeral_id string
  
  The ephemeral identifier of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.
- node.address string
  
  The network address of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.

GET /_cat/ml/datafeeds/{datafeed_id}

GET _cat/ml/datafeeds?v=true&format=json

resp = client.cat.ml_datafeeds(
    v=True,
    format="json",
)

const response = await client.cat.mlDatafeeds({
  v: "true",
  format: "json",
});

response = client.cat.ml_datafeeds(
  v: "true",
  format: "json"
)

$resp = $client->cat()->mlDatafeeds([
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/datafeeds?v=true&format=json"

client.cat().mlDatafeeds();

Response examples (200)

A successful response from `GET _cat/ml/datafeeds?v=true&format=json`.

[
  {
    "id": "datafeed-high_sum_total_sales",
    "state": "stopped",
    "buckets.count": "743",
    "search.count": "7"
  },
  {
    "id": "datafeed-low_request_rate",
    "state": "stopped",
    "buckets.count": "1457",
    "search.count": "3"
  },
  {
    "id": "datafeed-response_code_rates",
    "state": "stopped",
    "buckets.count": "1460",
    "search.count": "18"
  },
  {
    "id": "datafeed-url_scanning",
    "state": "stopped",
    "buckets.count": "1460",
    "search.count": "18"
  }
]

Ping the cluster Generally available

HEAD /

Api key auth

Get information about whether the cluster is running.

Responses

200 application/json

HEAD /

curl \
 --request HEAD 'http://api.example.com/' \
 --header "Authorization: $API_KEY"

Delete a connector Beta

DELETE /_connector/{connector_id}

Api key auth

Removes a connector and associated sync jobs. This is a destructive action that is not recoverable. NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector. These need to be removed manually.

Path parameters

connector_id string Required

The unique identifier of the connector to be deleted

Query parameters

delete_sync_jobs boolean

A flag indicating if associated sync jobs should be also removed. Defaults to false.
hard boolean

A flag indicating if the connector should be hard deleted.

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 /_connector/{connector_id}

DELETE _connector/my-connector-id&delete_sync_jobs=true

resp = client.connector.delete(
    connector_id="my-connector-id&delete_sync_jobs=true",
)

const response = await client.connector.delete({
  connector_id: "my-connector-id&delete_sync_jobs=true",
});

response = client.connector.delete(
  connector_id: "my-connector-id&delete_sync_jobs=true"
)

$resp = $client->connector()->delete([
    "connector_id" => "my-connector-id&delete_sync_jobs=true",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector-id&delete_sync_jobs=true"

client.connector().delete(d -> d
    .connectorId("my-connector-id&delete_sync_jobs=true")
);

Response examples (200)

{
    "acknowledged": true
}

Create a connector Beta

POST /_connector

Api key auth

Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. Self-managed connectors (Connector clients) are self-managed on your infrastructure.

application/json

Body

description string
index_name string
is_native boolean
language string
name string
service_type string

Responses

200 application/json
Hide response attributes Show response attributes object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- id string Required

POST /_connector

curl \
 --request POST 'http://api.example.com/_connector' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"description":"string","index_name":"string","is_native":true,"language":"string","name":"string","service_type":"string"}'

Cancel a connector sync job Beta

PUT /_connector/_sync_job/{connector_sync_job_id}/_cancel

Api key auth

Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time. The connector service is then responsible for setting the status of connector sync jobs to cancelled.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job

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/_sync_job/{connector_sync_job_id}/_cancel

PUT _connector/_sync_job/my-connector-sync-job-id/_cancel

resp = client.connector.sync_job_cancel(
    connector_sync_job_id="my-connector-sync-job-id",
)

const response = await client.connector.syncJobCancel({
  connector_sync_job_id: "my-connector-sync-job-id",
});

response = client.connector.sync_job_cancel(
  connector_sync_job_id: "my-connector-sync-job-id"
)

$resp = $client->connector()->syncJobCancel([
    "connector_sync_job_id" => "my-connector-sync-job-id",
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id/_cancel"

client.connector().syncJobCancel(s -> s
    .connectorSyncJobId("my-connector-sync-job-id")
);

Delete a connector sync job Beta

DELETE /_connector/_sync_job/{connector_sync_job_id}

Api key auth

Remove a connector sync job and its associated data. This is a destructive action that is not recoverable.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job to be deleted

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 /_connector/_sync_job/{connector_sync_job_id}

DELETE _connector/_sync_job/my-connector-sync-job-id

resp = client.connector.sync_job_delete(
    connector_sync_job_id="my-connector-sync-job-id",
)

const response = await client.connector.syncJobDelete({
  connector_sync_job_id: "my-connector-sync-job-id",
});

response = client.connector.sync_job_delete(
  connector_sync_job_id: "my-connector-sync-job-id"
)

$resp = $client->connector()->syncJobDelete([
    "connector_sync_job_id" => "my-connector-sync-job-id",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id"

client.connector().syncJobDelete(s -> s
    .connectorSyncJobId("my-connector-sync-job-id")
);

Response examples (200)

{
  "acknowledged": true
}

Get all connector sync jobs Beta

GET /_connector/_sync_job

Api key auth

Get information about all stored connector sync jobs listed by their creation date in ascending order.

Query parameters

from number

Starting offset (default: 0)
size number

Specifies a max number of results to get
status string

A sync job status to fetch connector sync jobs for

Values are canceling, canceled, completed, error, in_progress, pending, or suspended.
connector_id string

A connector id to fetch connector sync jobs for
job_type string | array[string]

A comma-separated list of job types to fetch the sync jobs for

Supported values include: full, incremental, access_control

Values are full, incremental, or access_control.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- results array[object] Required
  
  Hide results attributes Show results attributes object
  
  cancelation_requested_at string | number
  
  One of:
  string-1 string UnitMillis number
  
  canceled_at string | number
  
  One of:
  string-1 string UnitMillis number
  
  completed_at string | number
  
  One of:
  string-1 string UnitMillis number
  
  connector object Required
  
  Hide connector attributes Show connector attributes object
  
  configuration object Required
  
  filtering object Required
  
  id string Required
  
  index_name string Required
  
  language string
  
  pipeline object
  
  service_type string Required
  
  sync_cursor object
  
  created_at string | number
  
  One of:
  string-1 string UnitMillis number
  
  deleted_document_count number Required
  
  error string
  
  id string Required
  
  indexed_document_count number Required
  
  indexed_document_volume number Required
  
  job_type string Required
  
  Values are full, incremental, or access_control.
  
  last_seen string | number
  
  One of:
  string-1 string UnitMillis number
  
  metadata object Required
  
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties
  
  started_at string | number
  
  One of:
  string-1 string UnitMillis number
  
  status string Required
  
  Values are canceling, canceled, completed, error, in_progress, pending, or suspended.
  
  total_document_count number Required
  
  trigger_method string Required
  
  Values are on_demand or scheduled.
  
  worker_hostname string

GET /_connector/_sync_job

GET _connector/_sync_job?connector_id=my-connector-id&size=1

resp = client.connector.sync_job_list(
    connector_id="my-connector-id",
    size="1",
)

const response = await client.connector.syncJobList({
  connector_id: "my-connector-id",
  size: 1,
});

response = client.connector.sync_job_list(
  connector_id: "my-connector-id",
  size: "1"
)

$resp = $client->connector()->syncJobList([
    "connector_id" => "my-connector-id",
    "size" => "1",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job?connector_id=my-connector-id&size=1"

client.connector().syncJobList(s -> s
    .connectorId("my-connector-id")
    .size(1)
);

Activate the connector draft filter Technical preview

PUT /_connector/{connector_id}/_filtering/_activate

Api key auth

Activates the valid draft filtering for a connector.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

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}/_filtering/_activate

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_activate' \
 --header "Authorization: $API_KEY"

Update the connector API key ID Beta

PUT /_connector/{connector_id}/_api_key_id

Api key auth

Update the api_key_id and api_key_secret_id fields of a connector. You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored. The connector secret ID is required only for Elastic managed (native) connectors. Self-managed connectors (connector clients) do not use this field.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

api_key_id string
api_key_secret_id string

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}/_api_key_id

PUT _connector/my-connector/_api_key_id
{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

resp = client.connector.update_api_key_id(
    connector_id="my-connector",
    api_key_id="my-api-key-id",
    api_key_secret_id="my-connector-secret-id",
)

const response = await client.connector.updateApiKeyId({
  connector_id: "my-connector",
  api_key_id: "my-api-key-id",
  api_key_secret_id: "my-connector-secret-id",
});

response = client.connector.update_api_key_id(
  connector_id: "my-connector",
  body: {
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
  }
)

$resp = $client->connector()->updateApiKeyId([
    "connector_id" => "my-connector",
    "body" => [
        "api_key_id" => "my-api-key-id",
        "api_key_secret_id" => "my-connector-secret-id",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"api_key_id":"my-api-key-id","api_key_secret_id":"my-connector-secret-id"}' "$ELASTICSEARCH_URL/_connector/my-connector/_api_key_id"

client.connector().updateApiKeyId(u -> u
    .apiKeyId("my-api-key-id")
    .apiKeySecretId("my-connector-secret-id")
    .connectorId("my-connector")
);

Request example

{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

Response examples (200)

{
  "result": "updated"
}

Update the connector error field Technical preview

PUT /_connector/{connector_id}/_error

Api key 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"
}

Update the connector draft filtering validation Technical preview

PUT /_connector/{connector_id}/_filtering/_validation

Api key auth

Update the draft filtering validation info for a connector.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

validation object Required
Hide validation attributes Show validation attributes object
- errors array[object] Required
  Hide errors attributes Show errors attributes object
  
  ids array[string] Required
  
  messages array[string] Required
- state string Required
  
  Values are edited, invalid, or valid.

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}/_filtering/_validation

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_validation' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"validation":{"errors":[{"ids":["string"],"messages":["string"]}],"state":"edited"}}'

Update the connector pipeline Beta

PUT /_connector/{connector_id}/_pipeline

Api key auth

When you create a new connector, the configuration of an ingest pipeline is populated with default settings.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

pipeline object Required
Hide pipeline attributes Show pipeline attributes object
- extract_binary_content boolean Required
- name string Required
- reduce_whitespace boolean Required
- run_ml_inference boolean Required

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}/_pipeline

PUT _connector/my-connector/_pipeline
{
    "pipeline": {
        "extract_binary_content": true,
        "name": "my-connector-pipeline",
        "reduce_whitespace": true,
        "run_ml_inference": true
    }
}

resp = client.connector.update_pipeline(
    connector_id="my-connector",
    pipeline={
        "extract_binary_content": True,
        "name": "my-connector-pipeline",
        "reduce_whitespace": True,
        "run_ml_inference": True
    },
)

const response = await client.connector.updatePipeline({
  connector_id: "my-connector",
  pipeline: {
    extract_binary_content: true,
    name: "my-connector-pipeline",
    reduce_whitespace: true,
    run_ml_inference: true,
  },
});

response = client.connector.update_pipeline(
  connector_id: "my-connector",
  body: {
    "pipeline": {
      "extract_binary_content": true,
      "name": "my-connector-pipeline",
      "reduce_whitespace": true,
      "run_ml_inference": true
    }
  }
)

$resp = $client->connector()->updatePipeline([
    "connector_id" => "my-connector",
    "body" => [
        "pipeline" => [
            "extract_binary_content" => true,
            "name" => "my-connector-pipeline",
            "reduce_whitespace" => true,
            "run_ml_inference" => true,
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"pipeline":{"extract_binary_content":true,"name":"my-connector-pipeline","reduce_whitespace":true,"run_ml_inference":true}}' "$ELASTICSEARCH_URL/_connector/my-connector/_pipeline"

client.connector().updatePipeline(u -> u
    .connectorId("my-connector")
    .pipeline(p -> p
        .extractBinaryContent(true)
        .name("my-connector-pipeline")
        .reduceWhitespace(true)
        .runMlInference(true)
    )
);

Request example

{
    "pipeline": {
        "extract_binary_content": true,
        "name": "my-connector-pipeline",
        "reduce_whitespace": true,
        "run_ml_inference": true
    }
}

Response examples (200)

{
  "result": "updated"
}

Update the connector service type Beta

PUT /_connector/{connector_id}/_service_type

Api key auth

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

service_type string Required

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}/_service_type

PUT _connector/my-connector/_service_type
{
    "service_type": "sharepoint_online"
}

resp = client.connector.update_service_type(
    connector_id="my-connector",
    service_type="sharepoint_online",
)

const response = await client.connector.updateServiceType({
  connector_id: "my-connector",
  service_type: "sharepoint_online",
});

response = client.connector.update_service_type(
  connector_id: "my-connector",
  body: {
    "service_type": "sharepoint_online"
  }
)

$resp = $client->connector()->updateServiceType([
    "connector_id" => "my-connector",
    "body" => [
        "service_type" => "sharepoint_online",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service_type":"sharepoint_online"}' "$ELASTICSEARCH_URL/_connector/my-connector/_service_type"

client.connector().updateServiceType(u -> u
    .connectorId("my-connector")
    .serviceType("sharepoint_online")
);

Request example

{
    "service_type": "sharepoint_online"
}

Response examples (200)

{
  "result": "updated"
}

Update the connector status Technical preview

PUT /_connector/{connector_id}/_status

Api key auth

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

status string Required

Values are created, needs_configuration, configured, connected, or error.

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}/_status

PUT _connector/my-connector/_status
{
    "status": "needs_configuration"
}

resp = client.connector.update_status(
    connector_id="my-connector",
    status="needs_configuration",
)

const response = await client.connector.updateStatus({
  connector_id: "my-connector",
  status: "needs_configuration",
});

response = client.connector.update_status(
  connector_id: "my-connector",
  body: {
    "status": "needs_configuration"
  }
)

$resp = $client->connector()->updateStatus([
    "connector_id" => "my-connector",
    "body" => [
        "status" => "needs_configuration",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"status":"needs_configuration"}' "$ELASTICSEARCH_URL/_connector/my-connector/_status"

client.connector().updateStatus(u -> u
    .connectorId("my-connector")
    .status(ConnectorStatus.NeedsConfiguration)
);

Request example

{
    "status": "needs_configuration"
}

Response examples (200)

{
  "result": "updated"
}

Get data streams Generally available

GET /_data_stream/{name}

Api key auth

All methods and paths for this operation:

GET /_data_stream

GET /_data_stream/{name}

Get information about one or more data streams.

Required authorization

Index privileges: view_index_metadata

Path parameters

name string | array[string]

Comma-separated list of data stream names used to limit the request. Wildcard (*) expressions are supported. If omitted, all data streams are returned.

Query parameters

expand_wildcards string | array[string]
Type of data stream that wildcard patterns can match. 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.
include_defaults boolean Generally available

If true, returns all relevant default configurations for the index template.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
verbose boolean

Whether the maximum timestamp for each data stream should be calculated and returned.

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  _meta object
  
  Custom metadata for the stream, copied from the _meta object of the stream’s matching index template. If empty, the response omits this property.
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  allow_custom_routing boolean
  
  If true, the data stream allows custom routing on write request.
  
  failure_store object
  
  Information about failure store backing indices
  
  Hide failure_store attributes Show failure_store attributes object
  
  enabled boolean Required
  
  indices array[object] Required
  
  rollover_on_write boolean Required
  
  generation number Required
  
  Current generation for the data stream. This number acts as a cumulative count of the stream’s rollovers, starting at 1.
  
  hidden boolean Required
  
  If true, the data stream is hidden.
  
  ilm_policy string
  
  Name of the current ILM lifecycle policy in the stream’s matching index template. This lifecycle policy is set in the index.lifecycle.name setting. If the template does not include a lifecycle policy, this property is not included in the response. NOTE: A data stream’s backing indices may be assigned different lifecycle policies. To retrieve the lifecycle policy for individual backing indices, use the get index settings API.
  
  next_generation_managed_by string Required
  
  Name of the lifecycle system that'll manage the next generation of the data stream.
  
  Values are Index Lifecycle Management, Data stream lifecycle, or Unmanaged.
  
  prefer_ilm boolean Required
  
  Indicates if ILM should take precedence over DSL in case both are configured to managed this data stream.
  
  indices array[object] Required
  
  Array of objects containing information about the data stream’s backing indices. The last item in this array contains information about the stream’s current write index.
  
  Hide indices attributes Show indices attributes object
  
  index_name string Required
  
  Name of the backing index.
  
  index_uuid string Required
  
  Universally unique identifier (UUID) for the index.
  
  ilm_policy string
  
  Name of the current ILM lifecycle policy configured for this backing index.
  
  managed_by string
  
  Name of the lifecycle system that's currently managing this backing index.
  
  Values are Index Lifecycle Management, Data stream lifecycle, or Unmanaged.
  
  prefer_ilm boolean
  
  Indicates if ILM should take precedence over DSL in case both are configured to manage this index.
  
  index_mode string
  
  The index mode of this backing index of the data stream.
  
  Values are standard, time_series, logsdb, or lookup.
  
  lifecycle object
  
  Contains the configuration for the data stream lifecycle of this data stream.
  
  Hide lifecycle attribute Show lifecycle attribute object
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.
  
  name string Required
  
  Name of the data stream.
  
  replicated boolean
  
  If true, the data stream is created and managed by cross-cluster replication and the local cluster can not write into this data stream or change its mappings.
  
  rollover_on_write boolean Required
  
  If true, the next write to this data stream will trigger a rollover first and the document will be indexed in the new backing index. If the rollover fails the indexing request will fail too.
  
  settings object Required Additional properties
  
  The settings specific to this data stream that will take precedence over the settings in the matching index template.
  
  Index settings
  
  mappings object
  
  The mappings specific to this data stream that will take precedence over the mappings in the matching index template.
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  status string Required
  
  Health status of the data stream. This health status is based on the state of the primary and replica shards of the stream’s backing indices.
  
  Supported values include:
  
  green (or GREEN): All shards are assigned.
  
  yellow (or YELLOW): All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired.
  
  red (or RED): One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
  
  unknown
  
  unavailable
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
  
  system boolean Generally available
  
  If true, the data stream is created and managed by an Elastic stack component and cannot be modified through normal user interaction.
  
  template string Required
  
  Name of the index template used to create the data stream’s backing indices. The template’s index pattern must match the name of this data stream.
  
  timestamp_field object Required
  
  Information about the @timestamp field in the data stream.
  
  Hide timestamp_field attribute Show timestamp_field attribute object
  
  name string Required
  
  Name of the timestamp field for the data stream, which must be @timestamp. The @timestamp field must be included in every document indexed to the data stream.
  
  index_mode string
  
  The index mode for the data stream that will be used for newly created backing indices.
  
  Values are standard, time_series, logsdb, or lookup.

GET /_data_stream/{name}

GET _data_stream/my-data-stream

resp = client.indices.get_data_stream(
    name="my-data-stream",
)

const response = await client.indices.getDataStream({
  name: "my-data-stream",
});

response = client.indices.get_data_stream(
  name: "my-data-stream"
)

$resp = $client->indices()->getDataStream([
    "name" => "my-data-stream",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream"

client.indices().getDataStream(g -> g
    .name("my-data-stream")
);

Response examples (200)

A successful response for retrieving information about a data stream.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-2099.03.07-000001",
          "index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        },
        {
          "index_name": ".ds-my-data-stream-2099.03.08-000002",
          "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 2,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "GREEN",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    },
    {
      "name": "my-data-stream-two",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-two-2099.03.08-000001",
          "index_uuid": "3liBu2SYS5axasRt6fUIpA",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 1,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "YELLOW",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    }
  ]
}

Get the status for a data stream lifecycle Generally available

GET /{index}/_lifecycle/explain

Api key auth

Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

External documentation

Path parameters

index string | array[string] Required

The name of the index to explain

Query parameters

include_defaults boolean

indicates if the API should return the default values the system uses for the index's lifecycle
master_timeout string

Specify timeout for connection to master

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  index string Required
  
  managed_by_lifecycle boolean Required
  
  index_creation_date_millis number
  
  Time unit for milliseconds
  
  time_since_index_creation string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  rollover_date_millis number
  
  Time unit for milliseconds
  
  time_since_rollover string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  lifecycle object
  
  Data stream lifecycle with rollover can be used to display the configuration including the default rollover conditions, if asked.
  
  Hide lifecycle attribute Show lifecycle attribute object
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.
  
  generation_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  error string

GET /{index}/_lifecycle/explain

GET .ds-metrics-2023.03.22-000001/_lifecycle/explain

resp = client.indices.explain_data_lifecycle(
    index=".ds-metrics-2023.03.22-000001",
)

const response = await client.indices.explainDataLifecycle({
  index: ".ds-metrics-2023.03.22-000001",
});

response = client.indices.explain_data_lifecycle(
  index: ".ds-metrics-2023.03.22-000001"
)

$resp = $client->indices()->explainDataLifecycle([
    "index" => ".ds-metrics-2023.03.22-000001",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/.ds-metrics-2023.03.22-000001/_lifecycle/explain"

client.indices().explainDataLifecycle(e -> e
    .index(".ds-metrics-2023.03.22-000001")
);

Response examples (200)

A successful response from `GET .ds-metrics-2023.03.22-000001/_lifecycle/explain`, which retrieves the lifecycle status for a data stream backing index. If the index is managed by a data stream lifecycle, the API will show the `managed_by_lifecycle` field set to `true` and the rest of the response will contain information about the lifecycle execution status for this index.

{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_lifecycle" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "rollover_date_millis" : 1679475564293,
      "time_since_rollover" : "121ms",
      "lifecycle" : { },
      "generation_time" : "121ms"
  }
}

The API reports any errors related to the lifecycle execution for the target index.

{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_lifecycle" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "lifecycle" : {
        "enabled": true
      },
      "error": "{\"type\":\"validation_exception\",\"reason\":\"Validation Failed: 1: this action would add [2] shards, but this cluster
currently has [4]/[3] maximum normal shards open;\"}"
  }
}

Get data stream lifecycles Generally available

GET /_data_stream/{name}/_lifecycle

Api key auth

Get the data stream lifecycle configuration of one or more data streams.

External documentation

Path parameters

name string | array[string] Required

Comma-separated list of data streams to limit the request. Supports wildcards (*). To target all data streams, omit this parameter or use * or _all.

Query parameters

expand_wildcards string | array[string]
Type of data stream that wildcard patterns can match. 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.
include_defaults boolean

If true, return all default settings in the response.
master_timeout string

Period to wait for a connection to the master node. 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
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  lifecycle object
  
  Data stream lifecycle with rollover can be used to display the configuration including the default rollover conditions, if asked.
  
  Hide lifecycle attribute Show lifecycle attribute object
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.

GET /_data_stream/{name}/_lifecycle

GET /_data_stream/{name}/_lifecycle?human&pretty

resp = client.indices.get_data_lifecycle(
    name="{name}",
    human=True,
    pretty=True,
)

const response = await client.indices.getDataLifecycle({
  name: "{name}",
  human: "true",
  pretty: "true",
});

response = client.indices.get_data_lifecycle(
  name: "{name}",
  human: "true",
  pretty: "true"
)

$resp = $client->indices()->getDataLifecycle([
    "name" => "{name}",
    "human" => "true",
    "pretty" => "true",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/%7Bname%7D/_lifecycle?human&pretty"

Response examples (200)

A successful response from `GET /_data_stream/{name}/_lifecycle?human&pretty`.

{
  "data_streams": [
    {
      "name": "my-data-stream-1",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d"
      }
    },
    {
      "name": "my-data-stream-2",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d"
      }
    }
  ]
}

Update data stream lifecycles Generally available

PUT /_data_stream/{name}/_lifecycle

Api key auth

Update the data stream lifecycle of the specified data streams.

External documentation

Path parameters

name string | array[string] Required

Comma-separated list of data streams used to limit the request. Supports wildcards (*). To target all data streams use * or _all.

Query parameters

expand_wildcards string | array[string]
Type of data stream that wildcard patterns can match. 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.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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.

application/json

Body

data_retention string

If defined, every document added to this data stream will be stored at least for this time frame. Any time after this duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely.
downsampling object

The downsampling configuration to execute for the managed backing index after rollover.
Hide downsampling attribute Show downsampling attribute object
- rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  The duration since rollover when this downsampling round should execute
  
  config object Required
  
  The downsample configuration to execute.
enabled boolean

If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

Default value is true.

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.

PUT /_data_stream/{name}/_lifecycle

PUT _data_stream/my-data-stream/_lifecycle
{
  "data_retention": "7d"
}

resp = client.indices.put_data_lifecycle(
    name="my-data-stream",
    data_retention="7d",
)

const response = await client.indices.putDataLifecycle({
  name: "my-data-stream",
  data_retention: "7d",
});

response = client.indices.put_data_lifecycle(
  name: "my-data-stream",
  body: {
    "data_retention": "7d"
  }
)

$resp = $client->indices()->putDataLifecycle([
    "name" => "my-data-stream",
    "body" => [
        "data_retention" => "7d",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"data_retention":"7d"}' "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_lifecycle"

client.indices().putDataLifecycle(p -> p
    .dataRetention(d -> d
        .time("7d")
    )
    .name("my-data-stream")
);

Request examples

{
  "data_retention": "7d"
}

This example configures two downsampling rounds.

{
    "downsampling": [
      {
        "after": "1d",
        "fixed_interval": "10m"
      },
      {
        "after": "7d",
        "fixed_interval": "1d"
      }
    ]
}

Response examples (200)

A successful response for configuring a data stream lifecycle.

{
  "acknowledged": true
}

Get data stream mappings Generally available

GET /_data_stream/{name}/_mappings

Api key auth

Get mapping information for one or more data streams.

Required authorization

Index privileges: view_index_metadata

Path parameters

name string | array[string] Required

A comma-separated list of data streams or data stream patterns. Supports wildcards (*).

Query parameters

master_timeout string

The period to wait for a connection to the master node. 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
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  The name of the data stream.
  
  mappings object Required
  
  The settings specific to this data stream
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  effective_mappings object Required
  
  The settings specific to this data stream merged with the settings from its template. These effective_settings are the settings that will be used when a new index is created for this data stream.
  
  Hide effective_mappings attributes Show effective_mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object

GET /_data_stream/{name}/_mappings

GET /_data_stream/my-data-stream/_mappings

resp = client.indices.get_data_stream_mappings(
    name="my-data-stream",
)

const response = await client.indices.getDataStreamMappings({
  name: "my-data-stream",
});

response = client.indices.get_data_stream_mappings(
  name: "my-data-stream"
)

$resp = $client->indices()->getDataStreamMappings([
    "name" => "my-data-stream",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_mappings"

Response examples (200)

This is a response to `GET /_data_stream/my-data-stream/_settings` where my-data-stream that has two settings set. The `effective_settings` field shows additional settings that are pulled from its template.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "mappings": {
        "properties": {
          "field1": {
            "type": "ip"
          },
          "field3": {
            "type": "text"
          }
        }
      },
      "effective_mappings": {
        "properties": {
          "field1": {
            "type": "ip"
          },
          "field2": {
            "type": "text"
          },
          "field3": {
            "type": "text"
          }
        }
      }
    }
  ]
}

Get data stream settings Generally available

GET /_data_stream/{name}/_settings

Api key auth

Get setting information for one or more data streams.

Required authorization

Index privileges: view_index_metadata

Path parameters

name string | array[string] Required

A comma-separated list of data streams or data stream patterns. Supports wildcards (*).

Query parameters

master_timeout string

The period to wait for a connection to the master node. 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
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  The name of the data stream.
  
  settings object Required Additional properties
  
  The settings specific to this data stream
  
  Index settings
  
  effective_settings object Required Additional properties
  
  The settings specific to this data stream merged with the settings from its template. These effective_settings are the settings that will be used when a new index is created for this data stream.
  
  Index settings

GET /_data_stream/{name}/_settings

GET /_data_stream/my-data-stream/_settings

resp = client.indices.get_data_stream_settings(
    name="my-data-stream",
)

const response = await client.indices.getDataStreamSettings({
  name: "my-data-stream",
});

response = client.indices.get_data_stream_settings(
  name: "my-data-stream"
)

$resp = $client->indices()->getDataStreamSettings([
    "name" => "my-data-stream",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_settings"

Response examples (200)

This is a response to `GET /_data_stream/my-data-stream/_settings` where my-data-stream that has two settings set. The `effective_settings` field shows additional settings that are pulled from its template.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      }
    }
  ]
}

Update data stream settings Generally available

PUT /_data_stream/{name}/_settings

Api key auth

This API can be used to override settings on specific data streams. These overrides will take precedence over what is specified in the template that the data stream matches. To prevent your data stream from getting into an invalid state, only certain settings are allowed. If possible, the setting change is applied to all backing indices. Otherwise, it will be applied when the data stream is next rolled over.

Required authorization

Index privileges: manage

Path parameters

name string | array[string] Required

A comma-separated list of data streams or data stream patterns.

Query parameters

dry_run boolean

If true, the request does not actually change the settings on any data streams or indices. Instead, it simulates changing the settings and reports back to the user what would have happened had these settings actually been applied.
master_timeout string

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

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.

application/json

Body Required

object

object Additional properties

Index settings

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  The data stream name.
  
  applied_to_data_stream boolean Required
  
  If the settings were successfully applied to the data stream (or would have been, if running in dry_run mode), it is true. If an error occurred, it is false.
  
  error string
  
  A message explaining why the settings could not be applied to the data stream.
  
  settings object Required Additional properties
  
  The settings that are specfic to this data stream that will override any settings from the matching index template.
  
  Index settings
  
  effective_settings object Required Additional properties
  
  The settings that are effective on this data stream, taking into account the settings from the matching index template and the settings specific to this data stream.
  
  Index settings
  
  index_settings_results object Required
  
  Information about whether and where each setting was applied.
  
  Hide index_settings_results attributes Show index_settings_results attributes object
  
  applied_to_data_stream_only array[string] Required
  
  The list of settings that were applied to the data stream but not to backing indices. These will be applied to the write index the next time the data stream is rolled over.
  
  applied_to_data_stream_and_backing_indices array[string] Required
  
  The list of settings that were applied to the data stream and to all of its backing indices. These settings will also be applied to the write index the next time the data stream is rolled over.
  
  errors array[object]

PUT /_data_stream/{name}/_settings

PUT /_data_stream/my-data-stream/_settings
{
  "index.lifecycle.name" : "new-test-policy",
  "index.number_of_shards": 11
}

resp = client.indices.put_data_stream_settings(
    name="my-data-stream",
    settings={
        "index.lifecycle.name": "new-test-policy",
        "index.number_of_shards": 11
    },
)

const response = await client.indices.putDataStreamSettings({
  name: "my-data-stream",
  settings: {
    "index.lifecycle.name": "new-test-policy",
    "index.number_of_shards": 11,
  },
});

response = client.indices.put_data_stream_settings(
  name: "my-data-stream",
  body: {
    "index.lifecycle.name": "new-test-policy",
    "index.number_of_shards": 11
  }
)

$resp = $client->indices()->putDataStreamSettings([
    "name" => "my-data-stream",
    "body" => [
        "index.lifecycle.name" => "new-test-policy",
        "index.number_of_shards" => 11,
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index.lifecycle.name":"new-test-policy","index.number_of_shards":11}' "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_settings"

Request example

This is a request to change two settings on a data stream.

{
  "index.lifecycle.name" : "new-test-policy",
  "index.number_of_shards": 11
}

Response examples (200)

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when two settings are successfully updated on the data stream. In this case, `index.number_of_shards` is only applied to the data stream -- it will be applied to the write index on rollover. The setting `index.lifecycle.name` is applied to the data stream and all backing indices.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      },
      "index_settings_results": {
        "applied_to_data_stream_only": [
          "index.number_of_shards"
        ],
        "applied_to_data_stream_and_backing_indices": [
          "index.lifecycle.name"
        ]
      }
    }
  ]
}

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a setting is successfully applied to the data stream, but one of the backing indices, `.ds-my-data-stream-2025.05.28-000001`, has a write block. The response reports that the setting was not successfully applied to that index.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      },
      "index_settings_results": {
        "applied_to_data_stream_only": [
          "index.number_of_shards"
        ],
        "applied_to_data_stream_and_backing_indices": [
          "index.lifecycle.name"
        ],
        "errors": [
          {
            "index": ".ds-my-data-stream-2025.05.28-000001",
            "error": "index [.ds-my-data-stream-2025.05.28-000001] blocked by: [FORBIDDEN/9/index metadata (api)];"
          }
        ]
      }
    }
  ]
}

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a user attempts to set a setting that is not allowed on a data stream. As a result, no change was applied to the data stream.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": false,
      "error": "Cannot set the following settings on a data stream: [index.number_of_replicas]",
      "settings": {},
      "effective_settings": {},
      "index_settings_results": {
        "applied_to_data_stream_only": [],
        "applied_to_data_stream_and_backing_indices": []
      }
    }
  ]
}

Create a new document in the index Generally available

POST /{index}/_create/{id}

Api key auth

All methods and paths for this operation:

PUT /{index}/_create/{id}

POST /{index}/_create/{id}

You can index a new JSON document with the /<target>/_doc/ or /<target>/_create/<_id> APIs Using _create guarantees that the document is indexed only if it does not already exist. It returns a 409 response when a document with a same ID already exists in the index. To update an existing document, you must use the /<target>/_doc/ API.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

To add a document using the PUT /<target>/_create/<_id> or POST /<target>/_create/<_id> request formats, you must have the create_doc, create, index, or write index privilege.
To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.

Automatic data stream creation requires a matching index template with data stream enabled.

Automatically create data streams and indices

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.

Automatic index creation is controlled by the action.auto_create_index setting. If it is true, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow.

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. It does not affect the creation of data streams.

Routing

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

Distributed

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

Active shards

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. To alter this behavior per operation, use the wait_for_active_shards request parameter.

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). Specifying a negative value or a number greater than the number of shard copies will throw an error.

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

Required authorization

Index privileges: create

External documentation

Path parameters

index string Required

The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream. If the target doesn't exist and doesn’t match a data stream template, this request creates the index.
id string Required

A unique identifier for the document. To automatically generate a document ID, use the POST /<target>/_doc/ request format.

Query parameters

include_source_on_error boolean

True or false if to include the document source in the error message in case of parsing errors.
pipeline string

The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter.
refresh string

If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

Values are true, false, or wait_for.
require_alias boolean

If true, the destination must be an index alias.
require_data_stream boolean

If true, the request's actions must target a data stream (existing or to be created).
routing string

A custom value that is used to route operations to a specific shard.
timeout string

The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. Elasticsearch waits for at least the specified timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.

This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.

Values are -1 or 0.
version number

The explicit version number for concurrency control. It must be a non-negative long number.
version_type string
The version type.

Supported values include:
- internal: Use internal versioning that starts at 1 and increments with each update or delete.
- external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
- external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. NOTE: The external_gte version type is meant for special use cases and should be used with care. If used incorrectly, it can result in loss of data.
- force: This option is deprecated because it can cause primary and replica shards to diverge.
Values are internal, external, external_gte, or force.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

Values are all or index-setting.

application/json

Body Required

object

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
  
  The unique identifier for the added document.
- _index string Required
  
  The name of the index the document was added to.
- _primary_term number
  
  The primary term assigned to the document for the indexing operation.
- result string Required
  
  The result of the indexing operation: created or updated.
  
  Values are created, updated, deleted, not_found, or noop.
- _seq_no number
  
  The sequence number assigned to the document for the indexing operation. Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.
- _shards object Required
  
  Information about the replication process of the operation.
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  The number of shards the operation or search attempted to run on but failed.
  
  successful number Required
  
  The number of shards the operation or search succeeded on.
  
  total number Required
  
  The number of shards the operation or search will run on overall.
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number
  
  status string
  
  primary boolean
  
  skipped number
- _version number Required
  
  The document version, which is incremented each time the document is updated.
- forced_refresh boolean

POST /{index}/_create/{id}

PUT my-index-000001/_create/1
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

resp = client.create(
    index="my-index-000001",
    id="1",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)

const response = await client.create({
  index: "my-index-000001",
  id: 1,
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});

response = client.create(
  index: "my-index-000001",
  id: "1",
  body: {
    "@timestamp": "2099-11-15T13:12:00",
    "message": "GET /search HTTP/1.1 200 1070000",
    "user": {
      "id": "kimchy"
    }
  }
)

$resp = $client->create([
    "index" => "my-index-000001",
    "id" => "1",
    "body" => [
        "@timestamp" => "2099-11-15T13:12:00",
        "message" => "GET /search HTTP/1.1 200 1070000",
        "user" => [
            "id" => "kimchy",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}' "$ELASTICSEARCH_URL/my-index-000001/_create/1"

client.create(c -> c
    .id("1")
    .index("my-index-000001")
    .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
);

Request example

Run `PUT my-index-000001/_create/1` to index a document into the `my-index-000001` index if no document with that ID exists.

{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

Response examples (200)

A successful response from `PUT my-index-000001/_create/1` which indexes a document.

{
   "_index": "my-index-000001",
   "_id": "1",
   "_version": 1,
   "result": "created",
   "_shards": {
     "total": 1,
     "successful": 1,
     "failed": 0
   },
   "_seq_no": 0,
   "_primary_term": 1
}

Delete documents Generally available

POST /{index}/_delete_by_query

Api key auth

Deletes documents that match the specified query.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:

read
delete or write

You can specify the query criteria in the request URI or the request body using the same syntax as the search API. When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails.

NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number.

While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. A bulk delete request is performed for each batch of matching documents. If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. Any delete requests that completed successfully still stick, they are not rolled back.

You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than max_docs until it has successfully deleted max_docs documents, or it has gone through every document in the source query.

Throttling delete requests

To control the rate at which delete by query issues batches of delete operations, you can set requests_per_second to any positive decimal number. This pads each batch with a wait time to throttle the rate. Set requests_per_second to -1 to disable throttling.

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. By default the batch size is 1000, so if requests_per_second is set to 500:

target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. This is "bursty" instead of "smooth".

Slicing

Delete by query supports sliced scroll to parallelize the delete process. This can improve efficiency and provide a convenient way to break the request down into smaller parts.

Setting slices to auto lets Elasticsearch choose the number of slices to use. This setting will use one slice per shard, up to a certain limit. If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. Adding slices to the delete by query operation creates sub-requests which means it has some quirks:

You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
Fetching the status of the task for the request with slices only contains the status of completed slices.
These sub-requests are individually addressable for things like cancellation and rethrottling.
Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
Canceling the request with slices will cancel each sub-request.
Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being deleted.
Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
Delete performance scales linearly across available resources with the number of slices.

Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources.

Cancel a delete by query operation

Any delete by query can be canceled using the task cancel API. For example:

POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel

The task ID can be found by using the get tasks API.

Cancellation should happen quickly but might take a few seconds. The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.

Required authorization

Index privileges: read,delete

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams or indices, omit this parameter or use * or _all.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
analyzer string

Analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.
analyze_wildcard boolean

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
conflicts string
What to do if delete by query hits version conflicts: abort or proceed.

Supported values include:
- abort: Stop reindexing if there are conflicts.
- proceed: Continue reindexing even if there are conflicts.
Values are abort or proceed.
default_operator string

The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

Values are and, AND, or, or OR.
df string

The field to use as default where no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.
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.
from number

Skips the specified number of documents.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
lenient boolean

If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.
max_docs number

The maximum number of documents to process. Defaults to all documents. When set to a value less then or equal to scroll_size, a scroll will not be used to retrieve the results for the operation.
preference string

The node or shard the operation should be performed on. It is random by default.
refresh boolean

If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes. This is different than the delete API's refresh parameter, which causes just the shard that received the delete request to be refreshed. Unlike the delete API, it does not support wait_for.
request_cache boolean

If true, the request cache is used for this request. Defaults to the index-level setting.
requests_per_second number

The throttle for this request in sub-requests per second.
routing string

A custom value used to route operations to a specific shard.
q string

A query in the Lucene query string syntax.
scroll string

The period to retain the search context for scrolling.

Values are -1 or 0.
scroll_size number

The size of the scroll request that powers the operation.
search_timeout string

The explicit timeout for each search request. It defaults to no timeout.

Values are -1 or 0.
search_type string
The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
slices number | string

The number of slices this task should be divided into.

Value is auto.
sort array[string] Deprecated

A comma-separated list of <field>:<direction> pairs.
stats array[string]

The specific tag of the request for logging and statistical purposes.
terminate_after number

The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
timeout string

The period each deletion request waits for active shards.

Values are -1 or 0.
version boolean

If true, returns the document version as part of a hit.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The timeout value controls how long each write request waits for unavailable shards to become available.

Values are all or index-setting.
wait_for_completion boolean

If true, the request blocks until the operation is complete. If false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at .tasks/task/${taskId}. When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space.

application/json

Body Required

max_docs number

The maximum number of documents to delete.
query object

The documents to delete specified with Query DSL.

External documentation
slice object

Slice the request manually using the provided slice ID and total number of slices.
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]

A sort object that specifies the order of deleted documents.
One of:
Field string SortOptions object array-2 array[string | object]

A sort object that specifies the order of deleted documents.
A sort object that specifies the order of deleted documents.
Hide attributes Show attributes

_score object

_doc object

_geo_distance object

Hide _geo_distance attribute Show _geo_distance attribute object

ignore_unmapped boolean

_script object
A sort object that specifies the order of deleted documents.

Responses

200 application/json
Hide response attributes Show response attributes object
- batches number
  
  The number of scroll responses pulled back by the delete by query.
- deleted number
  
  The number of documents that were successfully deleted.
- failures array[object]
  
  An array of failures if there were any unrecoverable errors during the process. If this array is not empty, the request ended abnormally because of those failures. Delete by query is implemented using batches and any failures cause the entire process to end but all failures in the current batch are collected into the array. You can use the conflicts option to prevent reindex from ending on version conflicts.
  
  Hide failures attributes Show failures attributes object
  
  cause object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide cause attributes Show cause attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  id string Required
  
  index string Required
  
  status number Required
- noops number
  
  This field is always equal to zero for delete by query. It exists only so that delete by query, update by query, and reindex APIs return responses with the same structure.
- requests_per_second number
  
  The number of requests per second effectively run during the delete by query.
- retries object
  
  The number of retries attempted by delete by query. bulk is the number of bulk actions retried. search is the number of search actions retried.
  
  Hide retries attributes Show retries attributes object
  
  bulk number Required
  
  The number of bulk actions retried.
  
  search number Required
  
  The number of search actions retried.
- slice_id number
- task string
- throttled string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- throttled_millis number
  
  Time unit for milliseconds
- throttled_until string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- throttled_until_millis number
  
  Time unit for milliseconds
- timed_out boolean
  
  If true, some requests run during the delete by query operation timed out.
- took number
  
  Time unit for milliseconds
- total number
  
  The number of documents that were successfully processed.
- version_conflicts number
  
  The number of version conflicts that the delete by query hit.

POST /{index}/_delete_by_query

POST /my-index-000001,my-index-000002/_delete_by_query
{
  "query": {
    "match_all": {}
  }
}

resp = client.delete_by_query(
    index="my-index-000001,my-index-000002",
    query={
        "match_all": {}
    },
)

const response = await client.deleteByQuery({
  index: "my-index-000001,my-index-000002",
  query: {
    match_all: {},
  },
});

response = client.delete_by_query(
  index: "my-index-000001,my-index-000002",
  body: {
    "query": {
      "match_all": {}
    }
  }
)

$resp = $client->deleteByQuery([
    "index" => "my-index-000001,my-index-000002",
    "body" => [
        "query" => [
            "match_all" => new ArrayObject([]),
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"match_all":{}}}' "$ELASTICSEARCH_URL/my-index-000001,my-index-000002/_delete_by_query"

client.deleteByQuery(d -> d
    .index(List.of("my-index-000001","my-index-000002"))
    .query(q -> q
        .matchAll(m -> m)
    )
);

Request examples

Run `POST /my-index-000001,my-index-000002/_delete_by_query` to delete all documents from multiple data streams or indices.

{
  "query": {
    "match_all": {}
  }
}

Run `POST my-index-000001/_delete_by_query` to delete a document by using a unique attribute.

{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  },
  "max_docs": 1
}

Run `POST my-index-000001/_delete_by_query` to slice a delete by query manually. Provide a slice ID and total number of slices.

{
  "slice": {
    "id": 0,
    "max": 2
  },
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}

Run `POST my-index-000001/_delete_by_query?refresh&slices=5` to let delete by query automatically parallelize using sliced scroll to slice on `_id`. The `slices` query parameter value specifies the number of slices to use.

{
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}

Response examples (200)

A successful response from `POST /my-index-000001/_delete_by_query`.

{
  "took" : 147,
  "timed_out": false,
  "total": 119,
  "deleted": 119,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1.0,
  "throttled_until_millis": 0,
  "failures" : [ ]
}

Check for a document source Generally available

HEAD /{index}/_source/{id}

Api key auth

Check whether a document source exists in an index. For example:

HEAD my-index-000001/_source/1

A document's source is not available if it is disabled in the mapping.

Required authorization

Index privileges: read

External documentation

Path parameters

index string Required

A comma-separated list of data streams, indices, and aliases. It supports wildcards (*).
id string Required

A unique identifier for the document.

Query parameters

preference string

The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
realtime boolean

If true, the request is real-time as opposed to near-real-time.
refresh boolean

If true, the request refreshes the relevant shards before retrieving the document. Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
routing string

A custom value used to route operations to a specific shard.
_source boolean | string | array[string]

Indicates whether to return the _source field (true or false) or lists the fields to return.
_source_excludes string | array[string]

A comma-separated list of source fields to exclude in the response.
_source_includes string | array[string]

A comma-separated list of source fields to include in the response.
version number

The version number for concurrency control. It must match the current version of the document for the request to succeed.
version_type string
The version type.

Supported values include:
- internal: Use internal versioning that starts at 1 and increments with each update or delete.
- external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
- external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. NOTE: The external_gte version type is meant for special use cases and should be used with care. If used incorrectly, it can result in loss of data.
- force: This option is deprecated because it can cause primary and replica shards to diverge.
Values are internal, external, external_gte, or force.

Responses

200 application/json

HEAD /{index}/_source/{id}

HEAD my-index-000001/_source/1

resp = client.exists_source(
    index="my-index-000001",
    id="1",
)

const response = await client.existsSource({
  index: "my-index-000001",
  id: 1,
});

response = client.exists_source(
  index: "my-index-000001",
  id: "1"
)

$resp = $client->existsSource([
    "index" => "my-index-000001",
    "id" => "1",
]);

curl --head -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_source/1"

client.existsSource(e -> e
    .id("1")
    .index("my-index-000001")
);

Delete an async EQL search Generally available

DELETE /_eql/search/{id}

Api key auth

Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.

Path parameters

id string Required

Identifier for the search to delete. A search ID is provided in the EQL search API's response for an async search. A search ID is also provided if the request’s keep_on_completion parameter is true.

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 /_eql/search/{id}

DELETE /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=

resp = client.eql.delete(
    id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
)

const response = await client.eql.delete({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
});

response = client.eql.delete(
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
)

$resp = $client->eql()->delete([
    "id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="

client.eql().delete(d -> d
    .id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
);

Get EQL search results Generally available

POST /{index}/_eql/search

Api key auth

All methods and paths for this operation:

GET /{index}/_eql/search

POST /{index}/_eql/search

Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

External documentation

Path parameters

index string | array[string] Required

The name of the index to scope the operation

Query parameters

allow_no_indices boolean

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
allow_partial_search_results boolean

If true, returns partial results if there are shard failures. If false, returns an error with no partial results.
allow_partial_sequence_results boolean

If true, sequence queries will return partial results in case of shard failures. If false, they will return no results at all. This flag has effect only if allow_partial_search_results is true.
expand_wildcards string | array[string]
Whether to expand wildcard expression to concrete indices that are open, closed or both.

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.
ccs_minimize_roundtrips boolean

Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
keep_alive string

Period for which the search and its results are stored on the cluster.

Values are -1 or 0.
keep_on_completion boolean

If true, the search and its results are stored on the cluster.
wait_for_completion_timeout string

Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.

Values are -1 or 0.

application/json

Body Required

query string Required

EQL query you wish to run.
case_sensitive boolean
event_category_field string

Field containing the event classification, such as process, file, or network.
tiebreaker_field string

Field used to sort hits with the same timestamp in ascending order
timestamp_field string

Field containing event timestamp. Default "@timestamp"
fetch_size number

Maximum number of events to search at a time for sequence queries.
filter object | array[object]

Query, written in Query DSL, used to filter the events on which the EQL query runs.

One of:
QueryContainer object array-2 array[object]

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
keep_alive string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
keep_on_completion boolean
wait_for_completion_timeout string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
allow_partial_search_results boolean

Allow query execution also in case of shard failures. If true, the query will keep running and will return results based on the available shards. For sequences, the behavior can be further refined using allow_partial_sequence_results

Default value is true.
allow_partial_sequence_results boolean

This flag applies only to sequences and has effect only if allow_partial_search_results=true. If true, the sequence query will return results based on the available shards, ignoring the others. If false, the sequence query will return successfully, but will always have empty results.

Default value is false.
size number

For basic queries, the maximum number of matching events to return. Defaults to 10
fields object | array[object]

Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.
One of:
FieldAndFormat object array-2 array[object]
A reference to a field with formatting instructions on how to return the value
Hide attributes Show attributes

field string Required

A wildcard pattern. The request returns values for field names matching this pattern.

format string

The format in which the values are returned.

include_unmapped boolean
A reference to a field with formatting instructions on how to return the value
Hide attributes Show attributes object

field string Required

A wildcard pattern. The request returns values for field names matching this pattern.

format string

The format in which the values are returned.

include_unmapped boolean
result_position string
Supported values include:
- tail: Return the most recent matches, similar to the Unix tail command.
- head: Return the earliest matches, similar to the Unix head command.
Values are tail or head.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  For type lookup
  
  target_field string
  
  For type lookup
  
  target_index string
  
  For type lookup
  
  script object
  
  Painless script executed at query time.
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  The id for a stored script.
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Field type, which can be: boolean, composite, date, double, geo_point, ip,keyword, long, or lookup.
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
max_samples_per_key number

By default, the response of a sample query contains up to 10 samples, with one sample per unique set of join keys. Use the size parameter to get a smaller or larger set of samples. To retrieve more than one sample per set of join keys, use the max_samples_per_key parameter. Pipes are not supported for sample queries.

Default value is 1.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
  
  Identifier for the search.
- is_partial boolean
  
  If true, the response does not contain complete search results.
- is_running boolean
  
  If true, the search request is still executing.
- took number
  
  Time unit for milliseconds
- timed_out boolean
  
  If true, the request timed out before completion.
- hits object Required
  
  Contains matching events and sequences. Also contains related metadata.
  
  Hide hits attributes Show hits attributes object
  
  total object
  
  Metadata about the number of matching events or sequences.
  
  Hide total attributes Show total attributes object
  
  relation string Required
  
  Supported values include:
  
  eq: Accurate
  
  gte: Lower bound, including returned events or sequences
  
  Values are eq or gte.
  
  value number Required
  
  events array[object]
  
  Contains events matching the query. Each object represents a matching event.
  
  Hide events attributes Show events attributes object
  
  _index string Required
  
  Name of the index containing the event.
  
  _id string Required
  
  Unique identifier for the event. This ID is only unique within the index.
  
  _source object Required
  
  Original JSON body passed for the event at index time.
  
  missing boolean
  
  Set to true for events in a timespan-constrained sequence that do not meet a given condition.
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * array[object] Additional properties
  
  sequences array[object]
  
  Contains event sequences matching the query. Each object represents a matching sequence. This parameter is only returned for EQL queries containing a sequence.
  
  Hide sequences attributes Show sequences attributes object
  
  events array[object] Required
  
  Contains events matching the query. Each object represents a matching event.
  
  join_keys array[object]
  
  Shared field values used to constrain matches in the sequence. These are defined using the by keyword in the EQL query syntax.
- shard_failures array[object]
  
  Contains information about shard failures (if any), in case allow_partial_search_results=true
  
  Hide shard_failures attributes Show shard_failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number
  
  status string
  
  primary boolean

POST /{index}/_eql/search

GET /my-data-stream/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

resp = client.eql.search(
    index="my-data-stream",
    query="\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
)

const response = await client.eql.search({
  index: "my-data-stream",
  query:
    '\n    process where (process.name == "cmd.exe" and process.pid != 2013)\n  ',
});

response = client.eql.search(
  index: "my-data-stream",
  body: {
    "query": "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "
  }
)

$resp = $client->eql()->search([
    "index" => "my-data-stream",
    "body" => [
        "query" => "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "}' "$ELASTICSEARCH_URL/my-data-stream/_eql/search"

client.eql().search(s -> s
    .index("my-data-stream")
    .query(" process where (process.name == \"cmd.exe\" and process.pid != 2013) ")
);

Request examples

Run `GET /my-data-stream/_eql/search` to search for events that have a `process.name` of `cmd.exe` and a `process.pid` other than `2013`.

{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

Run `GET /my-data-stream/_eql/search` to search for a sequence of events. The sequence starts with an event with an `event.category` of `file`, a `file.name` of `cmd.exe`, and a `process.pid` other than `2013`. It is followed by an event with an `event.category` of `process` and a `process.executable` that contains the substring `regsvr32`. These events must also share the same `process.pid` value.

{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}

Response examples (200)

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "AtOJ4UjUBAAx3XR5kcCM",
            "_source": {
              "@timestamp": "2099-12-06T11:04:07.000Z",
              "event": {
                "category": "file",
                "id": "dGCHwoeS",
                "sequence": 2
              },
              "file": {
                "accessed": "2099-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "pid": 2012,
                "name": "cmd.exe",
                "executable": "C:\\Windows\\System32\\cmd.exe"
              }
            }
          },
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "OQmfCaduce8zoHT93o4H",
            "_source": {
              "@timestamp": "2099-12-07T11:07:09.000Z",
              "event": {
                "category": "process",
                "id": "aR3NWVOs",
                "sequence": 4
              },
              "process": {
                "pid": 2012,
                "name": "regsvr32.exe",
                "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
                "executable": "C:\\Windows\\System32\\regsvr32.exe"
              }
            }
          }
        ]
      }
    ]
  }
}

Create or update a component template Generally available

POST /_component_template/{name}

Api key auth

All methods and paths for this operation:

PUT /_component_template/{name}

POST /_component_template/{name}

Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

An index template can be composed of multiple component templates. To use a component template, specify it in an index template’s composed_of list. Component templates are only applied to new data streams and indices as part of a matching index template.

Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.

Component templates are only used during index creation. For data streams, this includes data stream creation and the creation of a stream’s backing indices. Changes to component templates do not affect existing indices, including a stream’s backing indices.

You can use C-style /* *\/ block comments in component templates. You can include comments anywhere in the request body except before the opening curly bracket.

Applying component templates

You cannot directly apply a component template to a data stream or index. To be applied, a component template must be included in an index template's composed_of list.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string Required

Name of the component template to create. Elasticsearch includes the following built-in component templates: logs-mappings; logs-settings; metrics-mappings; metrics-settings;synthetics-mapping; synthetics-settings. Elastic Agent uses these templates to configure backing indices for its data streams. If you use Elastic Agent and want to overwrite one of these templates, set the version for your replacement template higher than the current version. If you don’t use Elastic Agent and want to disable all built-in component and index templates, set stack.templates.enabled to false using the cluster update settings API.

Query parameters

create boolean

If true, this request cannot replace or update existing component templates.
cause string

User defined reason for create the component template.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

application/json

Body Required

template object Required

The template to be applied which includes mappings, settings, or aliases configuration.
Hide template attributes Show template attributes object
- aliases object
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  Query used to limit documents the alias can access.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
- mappings object
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
- settings object Additional properties
  Index settings
- defaults object Additional properties
  
  Default settings, included when the request's include_default is true.
  
  Index settings
- data_stream string
- lifecycle object
  
  Data stream lifecycle applicable if this is a data stream.
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  If defined, every document added to this data stream will be stored at least for this time frame. Any time after this duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely.
  
  downsampling object
  
  The downsampling configuration to execute for the managed backing index after rollover.
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.
version number

Version number used to manage component templates externally. This number isn't automatically generated or incremented by Elasticsearch. To unset a version, replace the template without specifying a version.
_meta object

Optional user metadata about the component template. It may have any contents. This map is not automatically generated by Elasticsearch. This information is stored in the cluster state, so keeping it short is preferable. To unset _meta, replace the template without specifying this information.
Hide _meta attribute Show _meta attribute object
- * object Additional properties
deprecated boolean

Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.

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.

POST /_component_template/{name}

PUT _component_template/template_1
{
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "mappings": {
      "_source": {
        "enabled": false
      },
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date",
          "format": "EEE MMM dd HH:mm:ss Z yyyy"
        }
      }
    }
  }
}

resp = client.cluster.put_component_template(
    name="template_1",
    template={
        "settings": {
            "number_of_shards": 1
        },
        "mappings": {
            "_source": {
                "enabled": False
            },
            "properties": {
                "host_name": {
                    "type": "keyword"
                },
                "created_at": {
                    "type": "date",
                    "format": "EEE MMM dd HH:mm:ss Z yyyy"
                }
            }
        }
    },
)

const response = await client.cluster.putComponentTemplate({
  name: "template_1",
  template: {
    settings: {
      number_of_shards: 1,
    },
    mappings: {
      _source: {
        enabled: false,
      },
      properties: {
        host_name: {
          type: "keyword",
        },
        created_at: {
          type: "date",
          format: "EEE MMM dd HH:mm:ss Z yyyy",
        },
      },
    },
  },
});

response = client.cluster.put_component_template(
  name: "template_1",
  body: {
    "template": {
      "settings": {
        "number_of_shards": 1
      },
      "mappings": {
        "_source": {
          "enabled": false
        },
        "properties": {
          "host_name": {
            "type": "keyword"
          },
          "created_at": {
            "type": "date",
            "format": "EEE MMM dd HH:mm:ss Z yyyy"
          }
        }
      }
    }
  }
)

$resp = $client->cluster()->putComponentTemplate([
    "name" => "template_1",
    "body" => [
        "template" => [
            "settings" => [
                "number_of_shards" => 1,
            ],
            "mappings" => [
                "_source" => [
                    "enabled" => false,
                ],
                "properties" => [
                    "host_name" => [
                        "type" => "keyword",
                    ],
                    "created_at" => [
                        "type" => "date",
                        "format" => "EEE MMM dd HH:mm:ss Z yyyy",
                    ],
                ],
            ],
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"template":{"settings":{"number_of_shards":1},"mappings":{"_source":{"enabled":false},"properties":{"host_name":{"type":"keyword"},"created_at":{"type":"date","format":"EEE MMM dd HH:mm:ss Z yyyy"}}}}}' "$ELASTICSEARCH_URL/_component_template/template_1"

Request examples

{
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "mappings": {
      "_source": {
        "enabled": false
      },
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date",
          "format": "EEE MMM dd HH:mm:ss Z yyyy"
        }
      }
    }
  }
}

You can include index aliases in a component template. During index creation, the `{index}` placeholder in the alias name will be replaced with the actual index name that the template gets applied to.

{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "aliases": {
    "alias1": {},
    "alias2": {
      "filter": {
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    },
    "{index}-alias": {}
  }
}

Create an index Generally available

PUT /{index}

Api key auth

You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:

Settings for the index.
Mappings for fields in the index.
Index aliases

Wait for active shards

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out. The index creation response will indicate what happened. For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out. Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful. These values simply indicate whether the operation completed before the timeout. If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon. If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).

You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards. Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.

Required authorization

Index privileges: create_index,manage

Path parameters

index string Required
Name of the index you wish to create. Index names must meet the following criteria:
- Lowercase only
- Cannot include \, /, *, ?, ", <, >, |, (space character), ,, or #
- Indices prior to 7.0 could contain a colon (:), but that has been deprecated and will not be supported in later versions
- Cannot start with -, _, or +
- Cannot be . or ..
- Cannot be longer than 255 bytes (note thtat it is bytes, so multi-byte characters will reach the limit faster)
- Names starting with . are deprecated, except for hidden indices and internal indices managed by plugins

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Values are all or index-setting.

application/json

Body

aliases object

Aliases for the index.
Hide aliases attribute Show aliases attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  filter object
  
  Query used to limit documents the alias can access.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
mappings object
Mapping for fields in the index. If specified, this mapping can include:
- Field names
- Field data types
- Mapping parameters
Hide mappings attributes Show mappings attributes object
- all_field object
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
- date_detection boolean
- dynamic string
  
  Values are strict, runtime, true, or false.
- dynamic_date_formats array[string]
- dynamic_templates array[object]
- _field_names object
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
- index_field object
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
- _meta object
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- numeric_detection boolean
- properties object
- _routing object
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
- _size object
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
- _source object
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Supported values include:
  
  disabled
  
  stored
  
  synthetic: Instead of storing source documents on disk exactly as you send them, Elasticsearch can reconstruct source content on the fly upon retrieval.
  
  Values are disabled, stored, or synthetic.
- runtime object
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  For type lookup
  
  target_field string
  
  For type lookup
  
  target_index string
  
  For type lookup
  
  script object
  
  Painless script executed at query time.
  
  Hide script attributes Show script attributes object
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  options object
  
  type string Required
  
  Field type, which can be: boolean, composite, date, double, geo_point, ip,keyword, long, or lookup.
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- enabled boolean
- subobjects string
  
  Values are true or false.
- _data_stream_timestamp object
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
settings object Additional properties

Configuration options for the index.

Index settings

Responses

200 application/json
Hide response attributes Show response attributes object
- index string Required
- shards_acknowledged boolean Required
- acknowledged boolean Required

PUT /{index}

PUT /my-index-000001
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}

resp = client.indices.create(
    index="my-index-000001",
    settings={
        "number_of_shards": 3,
        "number_of_replicas": 2
    },
)

const response = await client.indices.create({
  index: "my-index-000001",
  settings: {
    number_of_shards: 3,
    number_of_replicas: 2,
  },
});

response = client.indices.create(
  index: "my-index-000001",
  body: {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 2
    }
  }
)

$resp = $client->indices()->create([
    "index" => "my-index-000001",
    "body" => [
        "settings" => [
            "number_of_shards" => 3,
            "number_of_replicas" => 2,
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"number_of_shards":3,"number_of_replicas":2}}' "$ELASTICSEARCH_URL/my-index-000001"

client.indices().create(c -> c
    .index("my-index-000001")
    .settings(s -> s
        .numberOfShards("3")
        .numberOfReplicas("2")
    )
);

Request examples

This request specifies the `number_of_shards` and `number_of_replicas`.

{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}

You can provide mapping definitions in the create index API requests.

{
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "field1": { "type": "text" }
    }
  }
}

You can provide mapping definitions in the create index API requests. Index alias names also support date math.

{
  "aliases": {
    "alias_1": {},
    "alias_2": {
      "filter": {
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    }
  }
}

Delete an alias Generally available

DELETE /{index}/_aliases/{name}

Api key auth

All methods and paths for this operation:

DELETE /{index}/_alias/{name}

DELETE /{index}/_aliases/{name}

Removes a data stream or index from an alias.

Required authorization

Index privileges: manage

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*).
name string | array[string] Required

Comma-separated list of aliases to remove. Supports wildcards (*). To remove all aliases, use * or _all.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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 attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- errors boolean

DELETE /{index}/_aliases/{name}

DELETE my-data-stream/_alias/my-alias

resp = client.indices.delete_alias(
    index="my-data-stream",
    name="my-alias",
)

const response = await client.indices.deleteAlias({
  index: "my-data-stream",
  name: "my-alias",
});

response = client.indices.delete_alias(
  index: "my-data-stream",
  name: "my-alias"
)

$resp = $client->indices()->deleteAlias([
    "index" => "my-data-stream",
    "name" => "my-alias",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-data-stream/_alias/my-alias"

client.indices().deleteAlias(d -> d
    .index("my-data-stream")
    .name("my-alias")
);

Get aliases Generally available

GET /{index}/_alias/{name}

Api key auth

All methods and paths for this operation:

GET /_alias

GET /_alias/{name}

GET /{index}/_alias

GET /{index}/_alias/{name}

Retrieves information for one or more data stream or index aliases.

Required authorization

Index privileges: view_index_metadata

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.
name string | array[string] Required

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

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
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. 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.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

Period to wait for a connection to the master node. 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
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  Query used to limit documents the alias can access.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
  
  is_hidden boolean Generally available
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.

GET /{index}/_alias/{name}

GET _alias

resp = client.indices.get_alias()

const response = await client.indices.getAlias();

response = client.indices.get_alias

$resp = $client->indices()->getAlias();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_alias"

client.indices().getAlias(g -> g);

Roll over to a new index Generally available

POST /{alias}/_rollover/{new_index}

Api key auth

All methods and paths for this operation:

POST /{alias}/_rollover

POST /{alias}/_rollover/{new_index}

TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

The rollover API creates a new index for a data stream or index alias. The API behavior depends on the rollover target.

Roll over a data stream

If you roll over a data stream, the API creates a new write index for the stream. The stream's previous write index becomes a regular backing index. A rollover also increments the data stream's generation.

Roll over an index alias with a write index

TIP: Prior to Elasticsearch 7.9, you'd typically use an index alias with a write index to manage time series data. Data streams replace this functionality, require less maintenance, and automatically integrate with data tiers.

If an index alias points to multiple indices, one of the indices must be a write index. The rollover API creates a new write index for the alias with is_write_index set to true. The API also sets is_write_index to false for the previous write index.

Roll over an index alias with one index

If you roll over an index alias that points to only one index, the API creates a new index for the alias and removes the original index from the alias.

NOTE: A rollover creates a new index and is subject to the wait_for_active_shards setting.

Increment index names for an alias

When you roll over an index alias, you can specify a name for the new index. If you don't specify a name and the current index ends with - and a number, such as my-index-000001 or my-index-3, the new index name increments that number. For example, if you roll over an alias with a current index of my-index-000001, the rollover creates a new index named my-index-000002. This number is always six characters and zero-padded, regardless of the previous index's name.

If you use an index alias for time series data, you can use date math in the index name to track the rollover date. For example, you can create an alias that points to an index named <my-index-{now/d}-000001>. If you create the index on May 6, 2099, the index's name is my-index-2099.05.06-000001. If you roll over the alias on May 7, 2099, the new index's name is my-index-2099.05.07-000002.

Required authorization

Index privileges: manage

Path parameters

alias string

Name of the data stream or index alias to roll over.
new_index string Required

Name of the index to create. Supports date math. Data streams do not support this parameter.

Query parameters

dry_run boolean

If true, checks whether the current index satisfies the specified conditions but does not perform a rollover.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Values are all or index-setting.
lazy boolean

If set to true, the rollover action will only mark a data stream to signal that it needs to be rolled over at the next write. Only allowed on data streams.

application/json

Body

aliases object

Aliases for the target index. Data streams do not support this parameter.
Hide aliases attribute Show aliases attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  filter object
  
  Query used to limit documents the alias can access.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
conditions object

Conditions for the rollover. If specified, Elasticsearch only performs the rollover if the current index satisfies these conditions. If this parameter is not specified, Elasticsearch performs the rollover unconditionally. If conditions are specified, at least one of them must be a max_* condition. The index will rollover if any max_* condition is satisfied and all min_* conditions are satisfied.
Hide conditions attributes Show conditions attributes object
- min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- Time unit for milliseconds
- min_docs number
- max_docs number
- max_size number | string
  
  One of:
  number-1 number string-2 string
- max_size_bytes number
- min_size number | string
  
  One of:
  number-1 number string-2 string
- min_size_bytes number
- max_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
- max_primary_shard_size_bytes number
- min_primary_shard_size number | string
  
  One of:
  number-1 number string-2 string
- min_primary_shard_size_bytes number
- max_primary_shard_docs number
- min_primary_shard_docs number
mappings object

Mapping for fields in the index. If specified, this mapping can include field names, field data types, and mapping paramaters.
Hide mappings attributes Show mappings attributes object
- all_field object
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
- date_detection boolean
- dynamic string
  
  Values are strict, runtime, true, or false.
- dynamic_date_formats array[string]
- dynamic_templates array[object]
- _field_names object
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
- index_field object
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
- _meta object
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- numeric_detection boolean
- properties object
- _routing object
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
- _size object
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
- _source object
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Supported values include:
  
  disabled
  
  stored
  
  synthetic: Instead of storing source documents on disk exactly as you send them, Elasticsearch can reconstruct source content on the fly upon retrieval.
  
  Values are disabled, stored, or synthetic.
- runtime object
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  For type lookup
  
  target_field string
  
  For type lookup
  
  target_index string
  
  For type lookup
  
  script object
  
  Painless script executed at query time.
  
  Hide script attributes Show script attributes object
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  options object
  
  type string Required
  
  Field type, which can be: boolean, composite, date, double, geo_point, ip,keyword, long, or lookup.
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- enabled boolean
- subobjects string
  
  Values are true or false.
- _data_stream_timestamp object
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
settings object

Configuration options for the index. Data streams do not support this parameter.
Hide settings attribute Show settings attribute object
- * object Additional properties

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- conditions object Required
  
  Hide conditions attribute Show conditions attribute object
  
  * boolean Additional properties
- dry_run boolean Required
- new_index string Required
- old_index string Required
- rolled_over boolean Required
- shards_acknowledged boolean Required

POST /{alias}/_rollover/{new_index}

POST my-data-stream/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}

resp = client.indices.rollover(
    alias="my-data-stream",
    conditions={
        "max_age": "7d",
        "max_docs": 1000,
        "max_primary_shard_size": "50gb",
        "max_primary_shard_docs": "2000"
    },
)

const response = await client.indices.rollover({
  alias: "my-data-stream",
  conditions: {
    max_age: "7d",
    max_docs: 1000,
    max_primary_shard_size: "50gb",
    max_primary_shard_docs: "2000",
  },
});

response = client.indices.rollover(
  alias: "my-data-stream",
  body: {
    "conditions": {
      "max_age": "7d",
      "max_docs": 1000,
      "max_primary_shard_size": "50gb",
      "max_primary_shard_docs": "2000"
    }
  }
)

$resp = $client->indices()->rollover([
    "alias" => "my-data-stream",
    "body" => [
        "conditions" => [
            "max_age" => "7d",
            "max_docs" => 1000,
            "max_primary_shard_size" => "50gb",
            "max_primary_shard_docs" => "2000",
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"conditions":{"max_age":"7d","max_docs":1000,"max_primary_shard_size":"50gb","max_primary_shard_docs":"2000"}}' "$ELASTICSEARCH_URL/my-data-stream/_rollover"

client.indices().rollover(r -> r
    .alias("my-data-stream")
    .conditions(c -> c
        .maxAge(m -> m
            .time("7d")
        )
        .maxDocs(1000L)
        .maxPrimaryShardSize("50gb")
        .maxPrimaryShardDocs(2000L)
    )
);

Request examples

Create a new index for a data stream

{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}

Create a new index for a data stream

{}

Response examples (200)

An abbreviated response from `GET /_segments`.

{
  "_shards": {},
  "indices": {
    "test": {
      "shards": {
        "0": [
          {
            "routing": {
              "state": "STARTED",
              "primary": true,
              "node": "zDC_RorJQCao9xf9pg3Fvw"
            },
            "num_committed_segments": 0,
            "num_search_segments": 1,
            "segments": {
              "_0": {
                "generation": 0,
                "num_docs": 1,
                "deleted_docs": 0,
                "size_in_bytes": 3800,
                "committed": false,
                "search": true,
                "version": "7.0.0",
                "compound": true,
                "attributes": {}
              }
            }
          }
        ]
      }
    }
  }
}

Simulate an index Generally available

POST /_index_template/_simulate_index/{name}

Api key auth

Get the index configuration that would be applied to the specified index from an existing index template.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string Required

Name of the index to simulate

Query parameters

create boolean

Whether the index template we optionally defined in the body should only be dry-run added if new or can also replace an existing one
cause string

User defined reason for dry-run creating the new template for simulation purposes
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
include_defaults boolean Generally available

If true, returns all relevant default configurations for the index template.

Responses

200 application/json
Hide response attributes Show response attributes object
- overlapping array[object]
  
  Hide overlapping attributes Show overlapping attributes object
  
  name string Required
  
  index_patterns array[string] Required
- template object Required
  
  Hide template attributes Show template attributes object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  Query used to limit documents the alias can access.
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
  
  mappings object Required
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  settings object Required Additional properties
  Index settings

POST /_index_template/_simulate_index/{name}

POST /_index_template/_simulate_index/my-index-000001

resp = client.indices.simulate_index_template(
    name="my-index-000001",
)

const response = await client.indices.simulateIndexTemplate({
  name: "my-index-000001",
});

response = client.indices.simulate_index_template(
  name: "my-index-000001"
)

$resp = $client->indices()->simulateIndexTemplate([
    "name" => "my-index-000001",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_index_template/_simulate_index/my-index-000001"

client.indices().simulateIndexTemplate(s -> s
    .name("my-index-000001")
);

Response examples (200)

A successful response from `POST /_index_template/_simulate_index/my-index-000001`.

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_shards" : "2",
        "number_of_replicas" : "0",
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "template_1",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}

Perform inference on the service Generally available

POST /_inference/{task_type}/{inference_id}

Api key auth

All methods and paths for this operation:

POST /_inference/{inference_id}

POST /_inference/{task_type}/{inference_id}

This API enables you to use machine learning models to perform specific tasks on data that you provide as an input. It returns a response with the results of the tasks. The inference endpoint you use can perform one specific task that has been defined when the endpoint was created with the create inference API.

For details about using this API with a service, such as Amazon Bedrock, Anthropic, or HuggingFace, refer to the service-specific documentation.

The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

Required authorization

Cluster privileges: monitor_inference

Path parameters

task_type string Required

The type of inference task that the model performs.

Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.
inference_id string Required

The unique identifier for the inference endpoint.

Query parameters

timeout string

The amount of time to wait for the inference request to complete.

Values are -1 or 0.

application/json

Body

query string

The query input, which is required only for the rerank task. It is not required for other tasks.
input string | array[string] Required

The text on which you want to perform the inference task. It can be a single string or an array.

Inference endpoints for the completion task type currently only support a single string as input.

One of:
string-1 string array-2 array[string]
input_type string
Specifies the input data type for the text embedding model. The input_type parameter only applies to Inference Endpoints with the text_embedding task type. Possible values include:
- SEARCH
- INGEST
- CLASSIFICATION
- CLUSTERING Not all services support all values. Unsupported values will trigger a validation exception. Accepted values depend on the configured inference service, refer to the relevant service-specific documentation for more info.
The input_type parameter specified on the root level of the request body will take precedence over the input_type parameter specified in task_settings.
task_settings object

Task settings for the individual inference request. These settings are specific to the task type you specified and override the task settings specified when initializing the service.

Responses

200 application/json
Hide response attributes Show response attributes object
- text_embedding_bytes array[object]
  
  The text embedding result object for byte representation
  
  Hide text_embedding_bytes attribute Show text_embedding_bytes attribute object
  
  embedding array[number] Required
  
  Text Embedding results containing bytes are represented as Dense Vectors of bytes.
- text_embedding_bits array[object]
  
  The text embedding result object for byte representation
  
  Hide text_embedding_bits attribute Show text_embedding_bits attribute object
  
  embedding array[number] Required
  
  Text Embedding results containing bytes are represented as Dense Vectors of bytes.
- text_embedding array[object]
  
  The text embedding result object
  
  Hide text_embedding attribute Show text_embedding attribute object
  
  embedding array[number] Required
  
  Text Embedding results are represented as Dense Vectors of floats.
- sparse_embedding array[object]
  
  Hide sparse_embedding attribute Show sparse_embedding attribute object
  
  embedding object Required
  
  Sparse Embedding tokens are represented as a dictionary of string to double.
  
  Hide embedding attribute Show embedding attribute object
  
  * number Additional properties
- completion array[object]
  
  The completion result object
  
  Hide completion attribute Show completion attribute object
  
  result string Required
- rerank array[object]
  
  The rerank result object representing a single ranked document id: the original index of the document in the request relevance_score: the relevance_score of the document relative to the query text: Optional, the text of the document, if requested
  
  Hide rerank attributes Show rerank attributes object
  
  index number Required
  
  relevance_score number Required
  
  text string

POST /_inference/{task_type}/{inference_id}

curl \
 --request POST 'http://api.example.com/_inference/{task_type}/{inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":"string","input":"string","input_type":"string","task_settings":{}}'

Create an Amazon SageMaker inference endpoint Generally available

PUT /_inference/{task_type}/{amazonsagemaker_inference_id}

Api key auth

Create an inference endpoint to perform an inference task with the amazon_sagemaker service.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform.

Values are text_embedding, completion, chat_completion, sparse_embedding, or rerank.
amazonsagemaker_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

chunking_settings object

The chunking configuration object.
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
- separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
- separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
- strategy string
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  Default value is sentence.
  
  External documentation
service string Required

The type of service supported for the specified task type. In this case, amazon_sagemaker.

Value is amazon_sagemaker.
service_settings object Required

Settings used to install the inference model. These settings are specific to the amazon_sagemaker service and service_settings.api you specified.
Hide service_settings attributes Show service_settings attributes object
- access_key string Required
  
  A valid AWS access key that has permissions to use Amazon SageMaker and access to models for invoking requests.
- endpoint_name string Required
  
  The name of the SageMaker endpoint.
  
  External documentation
- api string Required
  
  The API format to use when calling SageMaker. Elasticsearch will convert the POST _inference request to this data format when invoking the SageMaker endpoint.
  
  Values are openai or elastic.
- region string Required
  
  The region that your endpoint or Amazon Resource Name (ARN) is deployed in. The list of available regions per model can be found in the Amazon SageMaker documentation.
  
  External documentation
- secret_key string Required
  
  A valid AWS secret key that is paired with the access_key. For information about creating and managing access and secret keys, refer to the AWS documentation.
  
  External documentation
- target_model string
  
  The model ID when calling a multi-model endpoint.
  
  External documentation
- target_container_hostname string
  
  The container to directly invoke when calling a multi-container endpoint.
  
  External documentation
- inference_component_name string
  
  The inference component to directly invoke when calling a multi-component endpoint.
  
  External documentation
- batch_size number
  
  The maximum number of inputs in each batch. This value is used by inference ingestion pipelines when processing semantic values. It correlates to the number of times the SageMaker endpoint is invoked (one per batch of input).
  
  Default value is 256.
- dimensions number
  
  The number of dimensions returned by the text embedding models. If this value is not provided, then it is guessed by making invoking the endpoint for the text_embedding task.
task_settings object

Settings to configure the inference task. These settings are specific to the task type and service_settings.api you specified.
Hide task_settings attributes Show task_settings attributes object
- custom_attributes string
  
  The AWS custom attributes passed verbatim through to the model running in the SageMaker Endpoint. Values will be returned in the X-elastic-sagemaker-custom-attributes header.
  
  External documentation
- enable_explanations string
  
  The optional JMESPath expression used to override the EnableExplanations provided during endpoint creation.
  
  External documentation
- inference_id string
  
  The capture data ID when enabled in the endpoint.
  
  External documentation
- session_id string
  
  The stateful session identifier for a new or existing session. New sessions will be returned in the X-elastic-sagemaker-new-session-id header. Closed sessions will be returned in the X-elastic-sagemaker-closed-session-id header.
  
  External documentation
- target_variant string
  
  Specifies the variant when running with multi-variant Endpoints.
  
  External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
  
  Settings specific to the service
- task_settings object
  
  Task settings specific to the service and task type
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  The task type
  
  Values are text_embedding, completion, chat_completion, sparse_embedding, or rerank.

PUT /_inference/{task_type}/{amazonsagemaker_inference_id}

PUT _inference/text_embedding/amazon_sagemaker_embeddings
{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint",
        "dimensions": 384,
        "element_type": "float"
    }
}

resp = client.inference.put(
    task_type="text_embedding",
    inference_id="amazon_sagemaker_embeddings",
    inference_config={
        "service": "amazon_sagemaker",
        "service_settings": {
            "access_key": "AWS-access-key",
            "secret_key": "AWS-secret-key",
            "region": "us-east-1",
            "api": "elastic",
            "endpoint_name": "my-endpoint",
            "dimensions": 384,
            "element_type": "float"
        }
    },
)

const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "amazon_sagemaker_embeddings",
  inference_config: {
    service: "amazon_sagemaker",
    service_settings: {
      access_key: "AWS-access-key",
      secret_key: "AWS-secret-key",
      region: "us-east-1",
      api: "elastic",
      endpoint_name: "my-endpoint",
      dimensions: 384,
      element_type: "float",
    },
  },
});

response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "amazon_sagemaker_embeddings",
  body: {
    "service": "amazon_sagemaker",
    "service_settings": {
      "access_key": "AWS-access-key",
      "secret_key": "AWS-secret-key",
      "region": "us-east-1",
      "api": "elastic",
      "endpoint_name": "my-endpoint",
      "dimensions": 384,
      "element_type": "float"
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "amazon_sagemaker_embeddings",
    "body" => [
        "service" => "amazon_sagemaker",
        "service_settings" => [
            "access_key" => "AWS-access-key",
            "secret_key" => "AWS-secret-key",
            "region" => "us-east-1",
            "api" => "elastic",
            "endpoint_name" => "my-endpoint",
            "dimensions" => 384,
            "element_type" => "float",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"amazon_sagemaker","service_settings":{"access_key":"AWS-access-key","secret_key":"AWS-secret-key","region":"us-east-1","api":"elastic","endpoint_name":"my-endpoint","dimensions":384,"element_type":"float"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/amazon_sagemaker_embeddings"

Request examples

Run `PUT _inference/text_embedding/amazon_sagemaker_embeddings` to create an inference endpoint that performs a text embedding task.

{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint",
        "dimensions": 384,
        "element_type": "float"
    }
}

Run `PUT _inference/completion/amazon_sagemaker_completion` to create an inference endpoint that performs a completion task.

{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}

Run `PUT _inference/chat_completion/amazon_sagemaker_chat_completion` to create an inference endpoint that performs a chat completion task.

{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}

Run `PUT _inference/sparse_embedding/amazon_sagemaker_sparse_embedding` to create an inference endpoint that performs a sparse embedding task.

{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}

Run `PUT _inference/rerank/amazon_sagemaker_rerank` to create an inference endpoint that performs a rerank task.

{
    "service": "amazon_sagemaker",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "api": "elastic",
        "endpoint_name": "my-endpoint"
    }
}

Create a Llama inference endpoint Generally available

PUT /_inference/{task_type}/{llama_inference_id}

Api key auth

Create an inference endpoint to perform an inference task with the llama service.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform.

Values are text_embedding, completion, or chat_completion.
llama_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

chunking_settings object

The chunking configuration object.
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
- separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
- separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
- strategy string
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  Default value is sentence.
  
  External documentation
service string Required

The type of service supported for the specified task type. In this case, llama.

Value is llama.
service_settings object Required

Settings used to install the inference model. These settings are specific to the llama service.
Hide service_settings attributes Show service_settings attributes object
- url string Required
  The URL endpoint of the Llama stack endpoint. URL must contain:
  
  For text_embedding task - /v1/inference/embeddings.
  
  For completion and chat_completion tasks - /v1/openai/v1/chat/completions.
- model_id string Required
  The name of the model to use for the inference task. Refer to the Llama downloading models documentation for different ways of getting a list of available models and downloading them. Service has been tested and confirmed to be working with the following models:
  
  For text_embedding task - all-MiniLM-L6-v2.
  
  For completion and chat_completion tasks - llama3.2:3b.
  External documentation
- max_input_tokens number
  
  For a text_embedding task, the maximum number of tokens per input before chunking occurs.
- similarity string
  
  For a text_embedding task, the similarity measure. One of cosine, dot_product, l2_norm.
  
  Values are cosine, dot_product, or l2_norm.
- rate_limit object
  
  This setting helps to minimize the number of rate limit errors returned from the Llama API. By default, the llama service sets the number of requests allowed per minute to 3000.
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute. By default, the number of requests allowed per minute is set by each service as follows:
  
  alibabacloud-ai-search service: 1000
  
  anthropic service: 50
  
  azureaistudio service: 240
  
  azureopenai service and task type text_embedding: 1440
  
  azureopenai service and task type completion: 120
  
  cohere service: 10000
  
  elastic service and task type chat_completion: 240
  
  googleaistudio service: 360
  
  googlevertexai service: 30000
  
  hugging_face service: 3000
  
  jinaai service: 2000
  
  llama service: 3000
  
  mistral service: 240
  
  openai service and task type text_embedding: 3000
  
  openai service and task type completion: 500
  
  voyageai service: 2000
  
  watsonxai service: 120

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
  
  Settings specific to the service
- task_settings object
  
  Task settings specific to the service and task type
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  The task type
  
  Values are text_embedding, chat_completion, or completion.

PUT /_inference/{task_type}/{llama_inference_id}

PUT _inference/text_embedding/llama-text-embedding
{
  "service": "llama",
  "service_settings": {
    "url": "http://localhost:8321/v1/inference/embeddings",
    "dimensions": 384,
    "model_id": "all-MiniLM-L6-v2" 
  }
}

resp = client.inference.put(
    task_type="text_embedding",
    inference_id="llama-text-embedding",
    inference_config={
        "service": "llama",
        "service_settings": {
            "url": "http://localhost:8321/v1/inference/embeddings",
            "dimensions": 384,
            "model_id": "all-MiniLM-L6-v2"
        }
    },
)

const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "llama-text-embedding",
  inference_config: {
    service: "llama",
    service_settings: {
      url: "http://localhost:8321/v1/inference/embeddings",
      dimensions: 384,
      model_id: "all-MiniLM-L6-v2",
    },
  },
});

response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "llama-text-embedding",
  body: {
    "service": "llama",
    "service_settings": {
      "url": "http://localhost:8321/v1/inference/embeddings",
      "dimensions": 384,
      "model_id": "all-MiniLM-L6-v2"
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "llama-text-embedding",
    "body" => [
        "service" => "llama",
        "service_settings" => [
            "url" => "http://localhost:8321/v1/inference/embeddings",
            "dimensions" => 384,
            "model_id" => "all-MiniLM-L6-v2",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"llama","service_settings":{"url":"http://localhost:8321/v1/inference/embeddings","dimensions":384,"model_id":"all-MiniLM-L6-v2"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/llama-text-embedding"

Request examples

Run `PUT _inference/text_embedding/llama-text-embedding` to create a Llama inference endpoint that performs a `text_embedding` task.

{
  "service": "llama",
  "service_settings": {
    "url": "http://localhost:8321/v1/inference/embeddings",
    "dimensions": 384,
    "model_id": "all-MiniLM-L6-v2" 
  }
}

Run `PUT _inference/completion/llama-completion` to create a Llama inference endpoint that performs a `completion` task.

{
  "service": "llama",
  "service_settings": {
    "url": "http://localhost:8321/v1/openai/v1/chat/completions",
    "model_id": "llama3.2:3b" 
  }
}

Run `PUT _inference/chat-completion/llama-chat-completion` to create a Llama inference endpoint that performs a `chat_completion` task.

{
  "service": "llama",
  "service_settings": {
    "url": "http://localhost:8321/v1/openai/v1/chat/completions",
    "model_id": "llama3.2:3b" 
  }
}

Create an OpenAI inference endpoint Generally available

PUT /_inference/{task_type}/{openai_inference_id}

Api key auth

Create an inference endpoint to perform an inference task with the openai service or openai compatible APIs.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform. NOTE: The chat_completion task type only supports streaming and only through the _stream API.

Values are chat_completion, completion, or text_embedding.
openai_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

chunking_settings object

The chunking configuration object.
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
- separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
- separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
- strategy string
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  Default value is sentence.
  
  External documentation
service string Required

The type of service supported for the specified task type. In this case, openai.

Value is openai.
service_settings object Required

Settings used to install the inference model. These settings are specific to the openai service.
Hide service_settings attributes Show service_settings attributes object
- api_key string Required
  
  A valid API key of your OpenAI account. You can find your OpenAI API keys in your OpenAI account under the API keys section.
  
  IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.
  
  External documentation
- dimensions number
  
  The number of dimensions the resulting output embeddings should have. It is supported only in text-embedding-3 and later models. If it is not set, the OpenAI defined default for the model is used.
- model_id string Required
  
  The name of the model to use for the inference task. Refer to the OpenAI documentation for the list of available text embedding models.
  
  External documentation
- organization_id string
  
  The unique identifier for your organization. You can find the Organization ID in your OpenAI account under Settings > Organizations.
- rate_limit object
  
  This setting helps to minimize the number of rate limit errors returned from OpenAI. The openai service sets a default number of requests allowed per minute depending on the task type. For text_embedding, it is set to 3000. For completion, it is set to 500.
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute. By default, the number of requests allowed per minute is set by each service as follows:
  
  alibabacloud-ai-search service: 1000
  
  anthropic service: 50
  
  azureaistudio service: 240
  
  azureopenai service and task type text_embedding: 1440
  
  azureopenai service and task type completion: 120
  
  cohere service: 10000
  
  elastic service and task type chat_completion: 240
  
  googleaistudio service: 360
  
  googlevertexai service: 30000
  
  hugging_face service: 3000
  
  jinaai service: 2000
  
  llama service: 3000
  
  mistral service: 240
  
  openai service and task type text_embedding: 3000
  
  openai service and task type completion: 500
  
  voyageai service: 2000
  
  watsonxai service: 120
- url string
  
  The URL endpoint to use for the requests. It can be changed for testing purposes.
  
  Default value is https://api.openai.com/v1/embeddings..
task_settings object

Settings to configure the inference task. These settings are specific to the task type you specified.
Hide task_settings attribute Show task_settings attribute object
- user string
  
  For a completion or text_embedding task, specify the user issuing the request. This information can be used for abuse detection.

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
  
  Settings specific to the service
- task_settings object
  
  Task settings specific to the service and task type
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  The task type
  
  Values are text_embedding, chat_completion, or completion.

PUT /_inference/{task_type}/{openai_inference_id}

PUT _inference/text_embedding/openai-embeddings
{
    "service": "openai",
    "service_settings": {
        "api_key": "OpenAI-API-Key",
        "model_id": "text-embedding-3-small",
        "dimensions": 128
    }
}

resp = client.inference.put(
    task_type="text_embedding",
    inference_id="openai-embeddings",
    inference_config={
        "service": "openai",
        "service_settings": {
            "api_key": "OpenAI-API-Key",
            "model_id": "text-embedding-3-small",
            "dimensions": 128
        }
    },
)

const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "openai-embeddings",
  inference_config: {
    service: "openai",
    service_settings: {
      api_key: "OpenAI-API-Key",
      model_id: "text-embedding-3-small",
      dimensions: 128,
    },
  },
});

response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "openai-embeddings",
  body: {
    "service": "openai",
    "service_settings": {
      "api_key": "OpenAI-API-Key",
      "model_id": "text-embedding-3-small",
      "dimensions": 128
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "openai-embeddings",
    "body" => [
        "service" => "openai",
        "service_settings" => [
            "api_key" => "OpenAI-API-Key",
            "model_id" => "text-embedding-3-small",
            "dimensions" => 128,
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"openai","service_settings":{"api_key":"OpenAI-API-Key","model_id":"text-embedding-3-small","dimensions":128}}' "$ELASTICSEARCH_URL/_inference/text_embedding/openai-embeddings"

client.inference().put(p -> p
    .inferenceId("openai-embeddings")
    .taskType(TaskType.TextEmbedding)
    .inferenceConfig(i -> i
        .service("openai")
        .serviceSettings(JsonData.fromJson("{\"api_key\":\"OpenAI-API-Key\",\"model_id\":\"text-embedding-3-small\",\"dimensions\":128}"))
    )
);

Request examples

Run `PUT _inference/text_embedding/openai-embeddings` to create an inference endpoint that performs a `text_embedding` task. The embeddings created by requests to this endpoint will have 128 dimensions.

{
    "service": "openai",
    "service_settings": {
        "api_key": "OpenAI-API-Key",
        "model_id": "text-embedding-3-small",
        "dimensions": 128
    }
}

Run `PUT _inference/completion/amazon_bedrock_completion` to create an inference endpoint to perform a completion task.

{
    "service": "amazonbedrock",
    "service_settings": {
        "access_key": "AWS-access-key",
        "secret_key": "AWS-secret-key",
        "region": "us-east-1",
        "provider": "amazontitan",
        "model": "amazon.titan-text-premier-v1:0"
    }
}

Create a Watsonx inference endpoint Generally available

PUT /_inference/{task_type}/{watsonx_inference_id}

Api key auth

Create an inference endpoint to perform an inference task with the watsonxai service. You need an IBM Cloud Databases for Elasticsearch deployment to use the watsonxai inference service. You can provision one through the IBM catalog, the Cloud Databases CLI plug-in, the Cloud Databases API, or Terraform.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform.

Values are text_embedding, chat_completion, or completion.
watsonx_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

service string Required

The type of service supported for the specified task type. In this case, watsonxai.

Value is watsonxai.
service_settings object Required

Settings used to install the inference model. These settings are specific to the watsonxai service.
Hide service_settings attributes Show service_settings attributes object
- api_key string Required
  
  A valid API key of your Watsonx account. You can find your Watsonx API keys or you can create a new one on the API keys page.
  
  IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.
  
  External documentation
- api_version string Required
  
  A version parameter that takes a version date in the format of YYYY-MM-DD. For the active version data parameters, refer to the Wastonx documentation.
  
  External documentation
- model_id string Required
  
  The name of the model to use for the inference task. Refer to the IBM Embedding Models section in the Watsonx documentation for the list of available text embedding models. Refer to the IBM library - Foundation models in Watsonx.ai.
  
  External documentation
- project_id string Required
  
  The identifier of the IBM Cloud project to use for the inference task.
- rate_limit object
  
  This setting helps to minimize the number of rate limit errors returned from Watsonx. By default, the watsonxai service sets the number of requests allowed per minute to 120.
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute. By default, the number of requests allowed per minute is set by each service as follows:
  
  alibabacloud-ai-search service: 1000
  
  anthropic service: 50
  
  azureaistudio service: 240
  
  azureopenai service and task type text_embedding: 1440
  
  azureopenai service and task type completion: 120
  
  cohere service: 10000
  
  elastic service and task type chat_completion: 240
  
  googleaistudio service: 360
  
  googlevertexai service: 30000
  
  hugging_face service: 3000
  
  jinaai service: 2000
  
  llama service: 3000
  
  mistral service: 240
  
  openai service and task type text_embedding: 3000
  
  openai service and task type completion: 500
  
  voyageai service: 2000
  
  watsonxai service: 120
- url string Required
  
  The URL of the inference endpoint that you created on Watsonx.

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string
  
  Only applicable to the recursive strategy and required when using it.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string]
  
  Only applicable to the recursive strategy and required when using it.
  
  A list of strings used as possible split points when chunking text.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
  
  Settings specific to the service
- task_settings object
  
  Task settings specific to the service and task type
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  The task type
  
  Values are text_embedding, chat_completion, or completion.

PUT /_inference/{task_type}/{watsonx_inference_id}

PUT _inference/text_embedding/watsonx-embeddings
{
  "service": "watsonxai",
  "service_settings": {
      "api_key": "Watsonx-API-Key", 
      "url": "Wastonx-URL", 
      "model_id": "ibm/slate-30m-english-rtrvr",
      "project_id": "IBM-Cloud-ID", 
      "api_version": "2024-03-14"
  }
}

resp = client.inference.put(
    task_type="text_embedding",
    inference_id="watsonx-embeddings",
    inference_config={
        "service": "watsonxai",
        "service_settings": {
            "api_key": "Watsonx-API-Key",
            "url": "Wastonx-URL",
            "model_id": "ibm/slate-30m-english-rtrvr",
            "project_id": "IBM-Cloud-ID",
            "api_version": "2024-03-14"
        }
    },
)

const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "watsonx-embeddings",
  inference_config: {
    service: "watsonxai",
    service_settings: {
      api_key: "Watsonx-API-Key",
      url: "Wastonx-URL",
      model_id: "ibm/slate-30m-english-rtrvr",
      project_id: "IBM-Cloud-ID",
      api_version: "2024-03-14",
    },
  },
});

response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "watsonx-embeddings",
  body: {
    "service": "watsonxai",
    "service_settings": {
      "api_key": "Watsonx-API-Key",
      "url": "Wastonx-URL",
      "model_id": "ibm/slate-30m-english-rtrvr",
      "project_id": "IBM-Cloud-ID",
      "api_version": "2024-03-14"
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "watsonx-embeddings",
    "body" => [
        "service" => "watsonxai",
        "service_settings" => [
            "api_key" => "Watsonx-API-Key",
            "url" => "Wastonx-URL",
            "model_id" => "ibm/slate-30m-english-rtrvr",
            "project_id" => "IBM-Cloud-ID",
            "api_version" => "2024-03-14",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"watsonxai","service_settings":{"api_key":"Watsonx-API-Key","url":"Wastonx-URL","model_id":"ibm/slate-30m-english-rtrvr","project_id":"IBM-Cloud-ID","api_version":"2024-03-14"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/watsonx-embeddings"

client.inference().put(p -> p
    .inferenceId("watsonx-embeddings")
    .taskType(TaskType.TextEmbedding)
    .inferenceConfig(i -> i
        .service("watsonxai")
        .serviceSettings(JsonData.fromJson("{\"api_key\":\"Watsonx-API-Key\",\"url\":\"Wastonx-URL\",\"model_id\":\"ibm/slate-30m-english-rtrvr\",\"project_id\":\"IBM-Cloud-ID\",\"api_version\":\"2024-03-14\"}"))
    )
);

Request example

Run `PUT _inference/text_embedding/watsonx-embeddings` to create an Watonsx inference endpoint that performs a text embedding task.

{
  "service": "watsonxai",
  "service_settings": {
      "api_key": "Watsonx-API-Key", 
      "url": "Wastonx-URL", 
      "model_id": "ibm/slate-30m-english-rtrvr",
      "project_id": "IBM-Cloud-ID", 
      "api_version": "2024-03-14"
  }
}

Perform text embedding inference on the service Generally available

POST /_inference/text_embedding/{inference_id}

Api key auth

Path parameters

inference_id string Required

The inference Id

Query parameters

timeout string

Specifies the amount of time to wait for the inference request to complete.

Values are -1 or 0.

application/json

Body

input string | array[string] Required

Inference input. Either a string or an array of strings.

One of:
string-1 string array-2 array[string]
task_settings object

Optional task settings

Responses

200 application/json
Hide response attributes Show response attributes object
- text_embedding_bytes array[object]
  
  The text embedding result object for byte representation
  
  Hide text_embedding_bytes attribute Show text_embedding_bytes attribute object
  
  embedding array[number] Required
  
  Text Embedding results containing bytes are represented as Dense Vectors of bytes.
- text_embedding_bits array[object]
  
  The text embedding result object for byte representation
  
  Hide text_embedding_bits attribute Show text_embedding_bits attribute object
  
  embedding array[number] Required
  
  Text Embedding results containing bytes are represented as Dense Vectors of bytes.
- text_embedding array[object]
  
  The text embedding result object
  
  Hide text_embedding attribute Show text_embedding attribute object
  
  embedding array[number] Required
  
  Text Embedding results are represented as Dense Vectors of floats.

POST /_inference/text_embedding/{inference_id}

POST _inference/text_embedding/my-cohere-endpoint
{
  "input": "The sky above the port was the color of television tuned to a dead channel.",
  "task_settings": {
    "input_type": "ingest"
  }
}

resp = client.inference.text_embedding(
    inference_id="my-cohere-endpoint",
    input="The sky above the port was the color of television tuned to a dead channel.",
    task_settings={
        "input_type": "ingest"
    },
)

const response = await client.inference.textEmbedding({
  inference_id: "my-cohere-endpoint",
  input:
    "The sky above the port was the color of television tuned to a dead channel.",
  task_settings: {
    input_type: "ingest",
  },
});

response = client.inference.text_embedding(
  inference_id: "my-cohere-endpoint",
  body: {
    "input": "The sky above the port was the color of television tuned to a dead channel.",
    "task_settings": {
      "input_type": "ingest"
    }
  }
)

$resp = $client->inference()->textEmbedding([
    "inference_id" => "my-cohere-endpoint",
    "body" => [
        "input" => "The sky above the port was the color of television tuned to a dead channel.",
        "task_settings" => [
            "input_type" => "ingest",
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"input":"The sky above the port was the color of television tuned to a dead channel.","task_settings":{"input_type":"ingest"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/my-cohere-endpoint"

client.inference().textEmbedding(t -> t
    .inferenceId("my-cohere-endpoint")
    .input("The sky above the port was the color of television tuned to a dead channel.")
    .taskSettings(JsonData.fromJson("{\"input_type\":\"ingest\"}"))
);

Request example

Run `POST _inference/text_embedding/my-cohere-endpoint` to perform text embedding on the example sentence using the Cohere integration,

{
  "input": "The sky above the port was the color of television tuned to a dead channel.",
  "task_settings": {
    "input_type": "ingest"
  }
}

Response examples (200)

An abbreviated response from `POST _inference/text_embedding/my-cohere-endpoint`.

{
  "text_embedding": [
    {
      "embedding": [
        {
          0.018569946,
          -0.036895752,
          0.01486969,
          -0.0045204163,
          -0.04385376,
          0.0075950623,
          0.04260254,
          -0.004005432,
          0.007865906,
          0.030792236,
          -0.050476074,
          0.011795044,
          -0.011642456,
          -0.010070801
        }
      ]
    }
  ]
}

Delete pipelines Generally available

DELETE /_ingest/pipeline/{id}

Api key auth

Delete one or more ingest pipelines.

External documentation

Path parameters

id string Required

Pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of *.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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 /_ingest/pipeline/{id}

DELETE /_ingest/pipeline/my-pipeline-id

resp = client.ingest.delete_pipeline(
    id="my-pipeline-id",
)

const response = await client.ingest.deletePipeline({
  id: "my-pipeline-id",
});

response = client.ingest.delete_pipeline(
  id: "my-pipeline-id"
)

$resp = $client->ingest()->deletePipeline([
    "id" => "my-pipeline-id",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ingest/pipeline/my-pipeline-id"

client.ingest().deletePipeline(d -> d
    .id("my-pipeline-id")
);

Get calendar configuration info Generally available

POST /_ml/calendars/{calendar_id}

Api key auth

All methods and paths for this operation:

GET /_ml/calendars

POST /_ml/calendars

GET /_ml/calendars/{calendar_id}

POST /_ml/calendars/{calendar_id}

Required authorization

Cluster privileges: monitor_ml

Path parameters

calendar_id string Required

A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using _all or * or by omitting the calendar identifier.

Query parameters

from number

Skips the specified number of calendars. This parameter is supported only when you omit the calendar identifier.
size number

Specifies the maximum number of calendars to obtain. This parameter is supported only when you omit the calendar identifier.

application/json

Body

page object

This object is supported only when you omit the calendar identifier.
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.

Responses

200 application/json
Hide response attributes Show response attributes object
- calendars array[object] Required
  
  Hide calendars attributes Show calendars attributes object
  
  calendar_id string Required
  
  A string that uniquely identifies a calendar.
  
  description string
  
  A description of the calendar.
  
  job_ids array[string] Required
  
  An array of anomaly detection job identifiers.
- count number Required

POST /_ml/calendars/{calendar_id}

GET _ml/calendars/planned-outages

resp = client.ml.get_calendars(
    calendar_id="planned-outages",
)

const response = await client.ml.getCalendars({
  calendar_id: "planned-outages",
});

response = client.ml.get_calendars(
  calendar_id: "planned-outages"
)

$resp = $client->ml()->getCalendars([
    "calendar_id" => "planned-outages",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages"

client.ml().getCalendars(g -> g
    .calendarId("planned-outages")
);

Compact and aligned text (CAT)

Get aliases Generally available

Required authorization

Path parameters

Query parameters

Responses

Get component templates Generally available

Required authorization

Path parameters

Query parameters

Responses

version string | null Required

Get a document count Generally available

Required authorization

Path parameters

Query parameters

Responses

epoch number | string

Get CAT help Generally available

Responses

Get datafeeds Generally available

Required authorization

Path parameters

Query parameters

Responses

Ping the cluster Generally available

Responses

Delete a connector Beta

Path parameters

Query parameters

Responses

Create a connector Beta

Body

Responses

Cancel a connector sync job Beta

Path parameters

Responses

Delete a connector sync job Beta

Path parameters

Responses

Get all connector sync jobs Beta

Query parameters

Responses

cancelation_requested_at string | number

canceled_at string | number

completed_at string | number

created_at string | number

last_seen string | number

started_at string | number

Activate the connector draft filter Technical preview

Path parameters

Responses

Update the connector API key ID Beta

Path parameters

Body Required

Responses

Update the connector error field Technical preview

Path parameters

Body Required

error string | null Required

Responses

Update the connector draft filtering validation Technical preview

Path parameters

Body Required

Responses

Update the connector pipeline Beta

Path parameters

Body Required

Responses

Update the connector service type Beta

Path parameters

Body Required

Responses

Update the connector status Technical preview

Path parameters

Body Required

Responses

Data stream

Get data streams Generally available

Required authorization