Elasticsearch API

Base URL 
http://api.example.com

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

Documentation source and versions

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

Last update on Mar 26, 2025.

This API is provided under license Apache 2.0.

Get transform information Added in 7.7.0

GET /_cat/transforms/{transform_id}
Api key auth Basic auth Bearer auth

Get configuration and usage information about transforms.

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 transform statistics API.

Path parameters

  • transform_id string Required

    A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.

Query parameters

  • allow_no_match boolean

    Specifies what to do when the request: contains wildcard expressions and there are no transforms 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, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. If false, the request returns a 404 status code when there are no matches or only partial matches.

  • from number

    Skips the specified number of transforms.

  • h string | array[string]

    Comma-separated list of column names to display.

  • s string | array[string]

    Comma-separated list of column names or column aliases used to sort the response.

  • time string

    The unit used to display time values.

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

  • size number

    The maximum number of transforms to obtain.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • id string
    • state string

      The status of the transform. Returned values include: aborting: The transform is aborting. failed: The transform failed. For more information about the failure, check thereasonfield. indexing: The transform is actively processing data and creating new documents. started: The transform is running but not actively indexing data. stopped: The transform is stopped. stopping`: The transform is stopping.

    • checkpoint string

      The sequence number for the checkpoint.

    • documents_processed string

      The number of documents that have been processed from the source index of the transform.

    • checkpoint_progress string | null

      The progress of the next checkpoint that is currently in progress.

      One of:
      string-1 string string-2 string | null

    • last_search_time string | null

      The timestamp of the last search in the source indices. This field is shown only if the transform is running.

      One of:
      string-1 string string-2 string | null

    • changes_last_detection_time string | null

      The timestamp when changes were last detected in the source indices.

      One of:
      string-1 string string-2 string | null
    • create_time string

      The time the transform was created.

    • version string
    • source_index string

      The source indices for the transform.

    • dest_index string

      The destination index for the transform.

    • pipeline string

      The unique identifier for the ingest pipeline.

    • description string

      The description of the transform.

    • transform_type string

      The type of transform: batch or continuous.

    • frequency string

      The interval between checks for changes in the source indices when the transform is running continuously.

    • max_page_search_size string

      The initial page size that is used for the composite aggregation for each checkpoint.

    • docs_per_second string

      The number of input documents per second.

    • reason string

      If a transform has a failed state, these details describe the reason for failure.

    • search_total string

      The total number of search operations on the source index for the transform.

    • search_failure string

      The total number of search failures.

    • search_time string

      The total amount of search time, in milliseconds.

    • index_total string

      The total number of index operations done by the transform.

    • index_failure string

      The total number of indexing failures.

    • index_time string

      The total time spent indexing documents, in milliseconds.

    • documents_indexed string

      The number of documents that have been indexed into the destination index for the transform.

    • delete_time string

      The total time spent deleting documents, in milliseconds.

    • documents_deleted string

      The number of documents deleted from the destination index due to the retention policy for the transform.

    • trigger_count string

      The number of times the transform has been triggered by the scheduler. For example, the scheduler triggers the transform indexer to check for updates or ingest new data at an interval specified in the frequency property.

    • pages_processed string

      The number of search or bulk index operations processed. Documents are processed in batches instead of individually.

    • processing_time string

      The total time spent processing results, in milliseconds.

    • checkpoint_duration_time_exp_avg string

      The exponential moving average of the duration of the checkpoint, in milliseconds.

    • indexed_documents_exp_avg string

      The exponential moving average of the number of new documents that have been indexed.

    • processed_documents_exp_avg string

      The exponential moving average of the number of documents that have been processed.
GET /_cat/transforms/{transform_id} 
curl \
 --request GET 'http://api.example.com/_cat/transforms/{transform_id}' \
 --header "Authorization: $API_KEY"
Response examples (200)
A successful response from `GET /_cat/transforms?v=true&format=json`. 
[
  {
    "id" : "ecommerce_transform",
    "state" : "started",
    "checkpoint" : "1",
    "documents_processed" : "705",
    "checkpoint_progress" : "100.00",
    "changes_last_detection_time" : null
  }
]

Set the connector sync job stats Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_stats
Api key auth Basic auth Bearer auth

Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. You can also update last_seen. This API is mainly used by the connector service for updating sync job information.

To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

Path parameters

application/json

Body Required

  • deleted_document_count number Required

    The number of documents the sync job deleted.

  • indexed_document_count number Required

    The number of documents the sync job indexed.

  • indexed_document_volume number Required

    The total size of the data (in MiB) the sync job indexed.

  • last_seen 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.

  • metadata object
    Hide metadata attribute Show metadata attribute object
    • * object Additional properties
  • total_document_count number

    The total number of documents in the target index after the sync job finished.

Responses

PUT /_connector/_sync_job/{connector_sync_job_id}/_stats 
curl \
 --request PUT 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_stats' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"deleted_document_count":42.0,"indexed_document_count":42.0,"indexed_document_volume":42.0,"last_seen":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}},"total_document_count":42.0}'
Request examples 
{
  "deleted_document_count": 42.0,
  "indexed_document_count": 42.0,
  "indexed_document_volume": 42.0,
  "last_seen": "string",
  "metadata": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "total_document_count": 42.0
}
Response examples (200) 
{}

Update the connector scheduling Beta

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

Path parameters

  • connector_id string Required

    The unique identifier of the connector to be updated

application/json

Body Required

  • scheduling object Required
    Hide scheduling attributes Show scheduling attributes object
    • access_control object
      Hide access_control attributes Show access_control attributes object
      • enabled boolean Required
      • interval string Required

        The interval is expressed using the crontab syntax

    • full object
      Hide full attributes Show full attributes object
      • enabled boolean Required
      • interval string Required

        The interval is expressed using the crontab syntax

    • incremental object
      Hide incremental attributes Show incremental attributes object
      • enabled boolean Required
      • interval string Required

        The interval is expressed using the crontab syntax

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}/_scheduling 
curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_scheduling' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"scheduling":{"access_control":{"enabled":true,"interval":"string"},"full":{"enabled":true,"interval":"string"},"incremental":{"enabled":true,"interval":"string"}}}'
Request examples 
{
  "scheduling": {
    "access_control": {
      "enabled": true,
      "interval": "string"
    },
    "full": {
      "enabled": true,
      "interval": "string"
    },
    "incremental": {
      "enabled": true,
      "interval": "string"
    }
  }
}
Response examples (200) 
{
  "result": "created"
}

Pause a follower Added in 6.5.0

POST /{index}/_ccr/pause_follow
Api key auth Basic auth Bearer auth

Pause a cross-cluster replication follower index. The follower index will not fetch any additional operations from the leader index. You can resume following with the resume follower API. You can pause and resume a follower index to change the configuration of the following task.

Path parameters

  • index string Required

    The name of the follower index that should pause following its leader index.

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 /{index}/_ccr/pause_follow 
curl \
 --request POST 'http://api.example.com/{index}/_ccr/pause_follow' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "acknowledged": true
}

Create or update an index template

PUT /_template/{name}
Api key auth Basic auth Bearer auth

Index templates define settings, mappings, and aliases that can be applied automatically to new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.

IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

Composable templates always take precedence over legacy templates. If no composable template matches a new index, matching legacy templates are applied according to their order.

Index templates are only applied during index creation. Changes to index templates do not affect existing indices. Settings and mappings specified in create index API requests override any settings or mappings specified in an index template.

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

Indices matching multiple templates

Multiple index templates can potentially match an index, in this case, both the settings and mappings are merged into the final configuration of the index. The order of the merging can be controlled using the order parameter, with lower order being applied first, and higher orders overriding them. NOTE: Multiple matching templates with the same order value will result in a non-deterministic merging order.

External documentation

Path parameters

  • name string Required

    The name of the template

Query parameters

  • create boolean

    If true, this request cannot replace or update existing index templates.

  • 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.

  • order number

    Order in which Elasticsearch applies this template if index matches multiple templates.

    Templates with lower 'order' values are merged first. Templates with higher 'order' values are merged later, overriding templates with lower values.

  • cause string

    User defined reason for creating/updating the index template

application/json

Body Required

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 /_template/{name} 
curl \
 --request PUT 'http://api.example.com/_template/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"mappings":{"_source":{"enabled":false}},"settings":{"number_of_shards":1},"properties":{"host_name":{"type":"keyword"},"created_at":{"type":"date","format":"EEE MMM dd HH:mm:ss Z yyyy"}},"index_patterns":["te*","bar*"]}'
Request example 
{
  "mappings": {
    "_source": {
      "enabled": false
    }
  },
  "settings": {
    "number_of_shards": 1
  },
  "properties": {
    "host_name": {
      "type": "keyword"
    },
    "created_at": {
      "type": "date",
      "format": "EEE MMM dd HH:mm:ss Z yyyy"
    }
  },
  "index_patterns": [
    "te*",
    "bar*"
  ]
}
Response examples (200) 
{
  "acknowledged": true
}

Get IP geolocation database configurations Added in 8.15.0

GET /_ingest/ip_location/database/{id}
Api key auth Basic auth Bearer auth

Path parameters

  • id string | array[string] Required

    Comma-separated list of database configuration IDs to retrieve. Wildcard (*) expressions are supported. To get all database configurations, omit this parameter or use *.

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. A value of -1 indicates that the request should never time out.

Responses

GET /_ingest/ip_location/database/{id} 
curl \
 --request GET 'http://api.example.com/_ingest/ip_location/database/{id}' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "databases": [
    {
      "id": "string",
      "version": 42.0,
      "": {
        "name": "string",
        "web": {},
        "local": {
          "type": "string"
        },
        "maxmind": {
          "account_id": "string"
        },
        "ipinfo": {}
      }
    }
  ]
}

Get GeoIP statistics Added in 7.13.0

GET /_ingest/geoip/stats
Api key auth Basic auth Bearer auth

Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

External documentation

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • stats object Required
      Hide stats attributes Show stats attributes object
    • nodes object Required

      Downloaded GeoIP2 databases for each node.

      Hide nodes attribute Show nodes attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • databases array[object] Required

          Downloaded databases for the node.

          Hide databases attribute Show databases attribute object
        • files_in_temp array[string] Required

          Downloaded database files, including related license files. Elasticsearch stores these files in the node’s temporary directory: $ES_TMPDIR/geoip-databases/.
GET /_ingest/geoip/stats 
curl \
 --request GET 'http://api.example.com/_ingest/geoip/stats' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "stats": {
    "successful_downloads": 42.0,
    "failed_downloads": 42.0,
    "": 42.0,
    "databases_count": 42.0,
    "skipped_updates": 42.0,
    "expired_databases": 42.0
  },
  "nodes": {
    "additionalProperty1": {
      "databases": [
        {
          "name": "string"
        }
      ],
      "files_in_temp": [
        "string"
      ]
    },
    "additionalProperty2": {
      "databases": [
        {
          "name": "string"
        }
      ],
      "files_in_temp": [
        "string"
      ]
    }
  }
}

Get calendar configuration info Added in 6.2.0

GET /_ml/calendars/{calendar_id}
Api key auth Basic auth Bearer auth

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
    Hide page attributes Show page attributes object
    • from number

      Skips the specified number of items.

    • size number

      Specifies the maximum number of items to obtain.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • calendars array[object] Required
      Hide calendars attributes Show calendars attributes object
    • count number Required
GET /_ml/calendars/{calendar_id} 
curl \
 --request GET 'http://api.example.com/_ml/calendars/{calendar_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"page":{"from":42.0,"size":42.0}}'
Request examples 
{
  "page": {
    "from": 42.0,
    "size": 42.0
  }
}
Response examples (200) 
{
  "calendars": [
    {
      "calendar_id": "string",
      "description": "string",
      "job_ids": [
        "string"
      ]
    }
  ],
  "count": 42.0
}

Get model snapshots info Added in 5.4.0

POST /_ml/anomaly_detectors/{job_id}/model_snapshots
Api key auth Basic auth Bearer auth

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

Query parameters

  • desc boolean

    If true, the results are sorted in descending order.

  • end string | number

    Returns snapshots with timestamps earlier than this time.

  • from number

    Skips the specified number of snapshots.

  • size number

    Specifies the maximum number of snapshots to obtain.

  • sort string

    Specifies the sort field for the requested snapshots. By default, the snapshots are sorted by their timestamp.

  • start string | number

    Returns snapshots with timestamps after this time.

application/json

Body

  • desc boolean

    Refer to the description for the desc query parameter.

  • end string | number

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

    One of:
    _types:DateTime string _types:UnitMillis number
  • page object
    Hide page attributes Show page attributes object
    • from number

      Skips the specified number of items.

    • size number

      Specifies the maximum number of items to obtain.

  • sort string

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

  • start string | number

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

    One of:
    _types:DateTime string _types:UnitMillis number

Responses

POST /_ml/anomaly_detectors/{job_id}/model_snapshots 
curl \
 --request POST 'http://api.example.com/_ml/anomaly_detectors/{job_id}/model_snapshots' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"desc":true,"":"string","page":{"from":42.0,"size":42.0},"sort":"string"}'
Request examples 
{
  "desc": true,
  "": "string",
  "page": {
    "from": 42.0,
    "size": 42.0
  },
  "sort": "string"
}
Response examples (200) 
{
  "count": 42.0,
  "model_snapshots": [
    {
      "description": "string",
      "job_id": "string",
      "latest_record_time_stamp": 42.0,
      "latest_result_time_stamp": 42.0,
      "min_version": "string",
      "model_size_stats": {
        "bucket_allocation_failures_count": 42.0,
        "job_id": "string",
        "": 42.0,
        "memory_status": "ok",
        "assignment_memory_basis": "string",
        "result_type": "string",
        "total_by_field_count": 42.0,
        "total_over_field_count": 42.0,
        "total_partition_field_count": 42.0,
        "categorization_status": "ok",
        "categorized_doc_count": 42.0,
        "dead_category_count": 42.0,
        "failed_category_count": 42.0,
        "frequent_category_count": 42.0,
        "rare_category_count": 42.0,
        "total_category_count": 42.0,
        "timestamp": 42.0
      },
      "retain": true,
      "snapshot_doc_count": 42.0,
      "snapshot_id": "string",
      "timestamp": 42.0
    }
  ]
}

Create or update a trained model alias Added in 7.13.0

PUT /_ml/trained_models/{model_id}/model_aliases/{model_alias}
Api key auth Basic auth Bearer auth

A trained model alias is a logical name used to reference a single trained model. You can use aliases instead of trained model identifiers to make it easier to reference your models. For example, you can use aliases in inference aggregations and processors. An alias must be unique and refer to only a single trained model. However, you can have multiple aliases for each trained model. If you use this API to update an alias such that it references a different trained model ID and the model uses a different type of data frame analytics, an error occurs. For example, this situation occurs if you have a trained model for regression analysis and a trained model for classification analysis; you cannot reassign an alias from one type of trained model to another. If you use this API to update an alias and there are very few input fields in common between the old and new trained models for the model alias, the API returns a warning.

Path parameters

  • model_id string Required

    The identifier for the trained model that the alias refers to.

  • model_alias string Required

    The alias to create or update. This value cannot end in numbers.

Query parameters

  • reassign boolean

    Specifies whether the alias gets reassigned to the specified trained model if it is already assigned to a different model. If the alias is already assigned and this parameter is false, the API returns an error.

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 /_ml/trained_models/{model_id}/model_aliases/{model_alias} 
curl \
 --request PUT 'http://api.example.com/_ml/trained_models/{model_id}/model_aliases/{model_alias}' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "acknowledged": true
}

Get rollup job information Deprecated Technical preview

GET /_rollup/job/{id}
Api key auth Basic auth Bearer auth

Get the configuration, stats, and status of rollup jobs.

NOTE: This API returns only active (both STARTED and STOPPED) jobs. If a job was created, ran for a while, then was deleted, the API does not return any details about it. For details about a historical rollup job, the rollup capabilities API may be more useful.

Path parameters

  • id string Required

    Identifier for the rollup job. If it is _all or omitted, the API returns all rollup jobs.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • jobs array[object] Required
      Hide jobs attributes Show jobs attributes object
      • config object Required
        Hide config attributes Show config attributes object
        • cron string Required
        • groups object Required
          Hide groups attributes Show groups attributes object
          • date_histogram object
            Hide date_histogram attributes Show date_histogram attributes object
            • delay 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.

            • field string Required

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

            • format string
            • interval 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.

            • calendar_interval 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.

            • fixed_interval 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_zone string
          • histogram object
            Hide histogram attributes Show histogram attributes object
            • fields string | array[string] Required
            • interval number Required

              The interval of histogram buckets to be generated when rolling up. For example, a value of 5 creates buckets that are five units wide (0-5, 5-10, etc). Note that only one interval can be specified in the histogram group, meaning that all fields being grouped via the histogram must share the same interval.

          • terms object
            Hide terms attribute Show terms attribute object
            • fields string | array[string] Required
        • id string Required
        • index_pattern string Required
        • metrics array[object] Required
          Hide metrics attributes Show metrics attributes object
          • field string Required

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

          • metrics array[string] Required

            An array of metrics to collect for the field. At least one metric must be configured.

            Values are min, max, sum, avg, or value_count.

        • page_size number Required
        • rollup_index string Required
        • timeout string Required

          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.

      • stats object Required
        Hide stats attributes Show stats attributes object
      • status object Required
        Hide status attributes Show status attributes object
GET /_rollup/job/{id} 
curl \
 --request GET 'http://api.example.com/_rollup/job/{id}' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "jobs": [
    {
      "config": {
        "cron": "string",
        "groups": {
          "date_histogram": {
            "delay": "string",
            "field": "string",
            "format": "string",
            "interval": "string",
            "calendar_interval": "string",
            "fixed_interval": "string",
            "time_zone": "string"
          },
          "histogram": {
            "fields": "string",
            "interval": 42.0
          },
          "terms": {
            "fields": "string"
          }
        },
        "id": "string",
        "index_pattern": "string",
        "metrics": [
          {
            "field": "string",
            "metrics": [
              "min"
            ]
          }
        ],
        "page_size": 42.0,
        "rollup_index": "string",
        "timeout": "string"
      },
      "stats": {
        "documents_processed": 42.0,
        "index_failures": 42.0,
        "": 42.0,
        "index_total": 42.0,
        "pages_processed": 42.0,
        "rollups_indexed": 42.0,
        "search_failures": 42.0,
        "search_total": 42.0,
        "trigger_count": 42.0,
        "processing_total": 42.0
      },
      "status": {
        "current_position": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "job_state": "started",
        "upgraded_doc_id": true
      }
    }
  ]
}

Run an async search Added in 7.7.0

POST /_async_search
Api key auth Basic auth Bearer auth

When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.

Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.

By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error. The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.

Query parameters

  • wait_for_completion_timeout string

    Blocks and waits until the search is completed up to a certain timeout. When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster.

  • keep_alive string

    Specifies how long the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period.

  • keep_on_completion boolean

    If true, results are stored for later retrieval when the search completes within the wait_for_completion_timeout.

  • 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

    Indicate if an error should be returned if there is a partial search failure or timeout

  • analyzer string

    The analyzer to use for the query string

  • analyze_wildcard boolean

    Specify whether wildcard and prefix queries should be analyzed (default: false)

  • batched_reduce_size number

    Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).

  • ccs_minimize_roundtrips boolean

    The default value is the only supported value.

  • default_operator string

    The default operator for query string query (AND or OR)

    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

  • docvalue_fields string | array[string]

    A comma-separated list of fields to return as the docvalue representation of a field for each hit

  • expand_wildcards string | array[string]

    Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • explain boolean

    Specify whether to return detailed information about score computation as part of a hit

  • ignore_throttled boolean

    Whether specified concrete, expanded or aliased indices should be ignored when throttled

  • ignore_unavailable boolean

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • lenient boolean

    Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

  • max_concurrent_shard_requests number

    The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests

  • min_compatible_shard_node string
  • preference string

    Specify the node or shard the operation should be performed on (default: random)

  • request_cache boolean

    Specify if request cache should be used for this request or not, defaults to true

  • routing string

    A comma-separated list of specific routing values

  • search_type string

    Search operation type

    Values are query_then_fetch or dfs_query_then_fetch.

  • stats array[string]

    Specific 'tag' of the request for logging and statistical purposes

  • stored_fields string | array[string]

    A comma-separated list of stored fields to return as part of a hit

  • suggest_field string

    Specifies which field to use for suggestions.

  • suggest_mode string

    Specify suggest mode

    Values are missing, popular, or always.

  • suggest_size number

    How many suggestions to return in response

  • suggest_text string

    The source text for which the suggestions should be returned.

  • terminate_after number

    The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.

  • timeout string

    Explicit operation timeout

  • track_total_hits boolean | number

    Indicate if the number of documents that match the query should be tracked. A number can also be specified, to accurately track the total hit count up to the number.

  • track_scores boolean

    Whether to calculate and return scores even if they are not used for sorting

  • typed_keys boolean

    Specify whether aggregation and suggester names should be prefixed by their respective types in the response

  • rest_total_hits_as_int boolean

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response

  • version boolean

    Specify whether to return document version as part of a hit

  • _source boolean | string | array[string]

    True or false to return the _source field or not, or a list of fields to return

  • _source_excludes string | array[string]

    A list of fields to exclude from the returned _source field

  • _source_includes string | array[string]

    A list of fields to extract and return from the _source field

  • seq_no_primary_term boolean

    Specify whether to return sequence number and primary term of the last modification of each hit

  • q string

    Query in the Lucene query string syntax

  • size number

    Number of hits to return (default: 10)

  • from number

    Starting offset (default: 0)

  • sort string | array[string]

    A comma-separated list of : pairs

application/json

Body

  • aggregations object
  • collapse object
    External documentation
  • explain boolean

    If true, returns detailed information about score computation as part of a hit.

  • ext object

    Configuration of search extensions defined by Elasticsearch plugins.

    Hide ext attribute Show ext attribute object
    • * object Additional properties
  • from number

    Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • highlight object
    Hide highlight attributes Show highlight attributes object
    • boundary_chars string

      A string that contains each boundary character.

    • boundary_max_scan number

      How far to scan for boundary characters.

    • boundary_scanner string

      Values are chars, sentence, or word.

    • boundary_scanner_locale string

      Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

    • force_source boolean Deprecated
    • fragmenter string

      Values are simple or span.

    • fragment_size number

      The size of the highlighted fragment in characters.

    • highlight_filter boolean
    • highlight_query object

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

      External documentation
    • max_fragment_length number
    • max_analyzed_offset number

      If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

    • no_match_size number

      The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

    • number_of_fragments number

      The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

    • options object
      Hide options attribute Show options attribute object
      • * object Additional properties
    • order string

      Value is score.

    • phrase_limit number

      Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

    • post_tags array[string]

      Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

    • pre_tags array[string]

      Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

    • require_field_match boolean

      By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

    • tags_schema string

      Value is styled.

    • encoder string

      Values are default or html.

    • fields object Required
  • track_total_hits boolean | number

    Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.

  • indices_boost array[object]

    Boosts the _score of documents from specified indices.

    Hide indices_boost attribute Show indices_boost attribute object
    • * number Additional properties
  • docvalue_fields array[object]

    Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

    Hide docvalue_fields attributes Show docvalue_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

      The format in which the values are returned.

    • include_unmapped boolean

  • knn object | array[object]

    Defines the approximate kNN search to run.

    One of:
    _types:KnnSearch object array-2 array[object]
    Hide attributes Show attributes
  • min_score number

    Minimum _score for matching documents. Documents with a lower _score are not included in the search results.

  • post_filter object

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

    External documentation
  • profile boolean
  • query object

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

    External documentation

  • rescore object | array[object]

    One of:
    _types:Rescore object array-2 array[object]
    Hide attributes Show attributes
    • window_size number
    • query object
      Hide query attributes Show query attributes object
    • learning_to_rank object
      Hide learning_to_rank attributes Show learning_to_rank attributes object
      • model_id string Required

        The unique identifier of the trained model uploaded to Elasticsearch

      • params object

        Named parameters to be passed to the query templates used for feature

        Hide params attribute Show params attribute object
        • * object Additional properties
  • script_fields object

    Retrieve a script evaluation (based on different fields) for each hit.

    Hide script_fields attribute Show script_fields attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
  • search_after array[number | string | boolean | null | object]

    A field value.

    A field value.

    One of:
    _types:FieldValue number _types:FieldValue number _types:FieldValue string _types:FieldValue boolean _types:FieldValue string | null _types:FieldValue object
  • size number

    The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • slice object
    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]

    One of:
    _types:Field string _types:SortOptions object _types:Sort array[string | object]

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

  • _source boolean | object

    Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

    One of:
    _types:SourceConfig boolean _types:SourceFilter object
  • fields array[object]

    Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

    Hide fields attributes Show 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

      The format in which the values are returned.

    • include_unmapped boolean
  • suggest object
    Hide suggest attribute Show suggest attribute object
    • text string

      Global suggest text, to avoid repetition when the same text is used in several suggesters

  • terminate_after number

    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. Defaults to 0, which does not terminate query execution early.

  • timeout string

    Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.

  • track_scores boolean

    If true, calculate and return document scores, even if the scores are not used for sorting.

  • version boolean

    If true, returns document version as part of a hit.

  • seq_no_primary_term boolean

    If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.

  • stored_fields string | array[string]
  • pit object
    Hide pit attributes Show pit attributes object
    • id string Required
    • 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.

  • 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

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

      • target_field string

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

      • target_index string
      • script object
        Hide script attributes Show script attributes object
      • type string Required

        Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

  • stats array[string]

    Stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

POST /_async_search 
curl \
 --request POST 'http://api.example.com/_async_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"sort\": [\n    { \"date\": { \"order\": \"asc\" } }\n  ],\n  \"aggs\": {\n    \"sale_date\": {\n      \"date_histogram\": {\n        \"field\": \"date\",\n        \"calendar_interval\": \"1d\"\n      }\n    }\n  }\n}"'
Request example
Perform a search request asynchronously with `POST /sales*/_async_search?size=0`. It accepts the same parameters and request body as the search API. 
{
  "sort": [
    { "date": { "order": "asc" } }
  ],
  "aggs": {
    "sale_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1d"
      }
    }
  }
}
Response examples (200)
A successful response when performing search asynchronously. 
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_partial" : true,
  "is_running" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "response" : {
    "took" : 1122,
    "timed_out" : false,
    "num_reduce_phases" : 0,
    "_shards" : {
      "total" : 562,
      "successful" : 3,
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 157483,
        "relation" : "gte"
      },
      "max_score" : null,
      "hits" : [ ]
    }
  }
}

Check user privileges Added in 6.4.0

POST /_security/user/_has_privileges
Api key auth Basic auth Bearer auth

Determine whether the specified user has a specified list of privileges. All users can use this API, but only to determine their own privileges. To check the privileges of other users, you must use the run as feature.

External documentation
application/json

Body Required

  • application array[object]
    Hide application attributes Show application attributes object
    • application string Required

      The name of the application.

    • privileges array[string] Required

      A list of the privileges that you want to check for the specified resources. It may be either application privilege names or the names of actions that are granted by those privileges

    • resources array[string] Required

      A list of resource names against which the privileges should be checked.

  • cluster array[string]

    A list of the cluster privileges that you want to check.

  • index array[object]
    Hide index attributes Show index attributes object
    • names string | array[string] Required
    • privileges array[string] Required

      A list of the privileges that you want to check for the specified indices.

    • allow_restricted_indices boolean

      This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices. Implicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false. If restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • application object Required
      Hide application attribute Show application attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
          • * boolean Additional properties
    • cluster object Required
      Hide cluster attribute Show cluster attribute object
      • * boolean Additional properties
    • has_all_requested boolean Required
    • index object Required
      Hide index attribute Show index attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
        • * boolean Additional properties
    • username string Required
POST /_security/user/_has_privileges 
curl \
 --request POST 'http://api.example.com/_security/user/_has_privileges' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"application":[{"application":"string","privileges":["string"],"resources":["string"]}],"cluster":["string"],"index":[{"names":"string","privileges":["string"],"allow_restricted_indices":true}]}'
Request examples 
{
  "application": [
    {
      "application": "string",
      "privileges": [
        "string"
      ],
      "resources": [
        "string"
      ]
    }
  ],
  "cluster": [
    "string"
  ],
  "index": [
    {
      "names": "string",
      "privileges": [
        "string"
      ],
      "allow_restricted_indices": true
    }
  ]
}
Response examples (200) 
{
  "application": {
    "additionalProperty1": {
      "additionalProperty1": {
        "additionalProperty1": true,
        "additionalProperty2": true
      },
      "additionalProperty2": {
        "additionalProperty1": true,
        "additionalProperty2": true
      }
    },
    "additionalProperty2": {
      "additionalProperty1": {
        "additionalProperty1": true,
        "additionalProperty2": true
      },
      "additionalProperty2": {
        "additionalProperty1": true,
        "additionalProperty2": true
      }
    }
  },
  "cluster": {
    "additionalProperty1": true,
    "additionalProperty2": true
  },
  "has_all_requested": true,
  "index": {
    "additionalProperty1": {
      "additionalProperty1": true,
      "additionalProperty2": true
    },
    "additionalProperty2": {
      "additionalProperty1": true,
      "additionalProperty2": true
    }
  },
  "username": "string"
}