Update data streams Added in 7.16.0

POST /_data_stream/_modify
Api key auth Basic auth Bearer auth

Performs one or more data stream modification actions in a single atomic operation.

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.
POST /_data_stream/_modify 
curl \
 --request POST 'http://api.example.com/_data_stream/_modify' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"actions":[{"add_backing_index":{"data_stream":"string","index":"string"},"remove_backing_index":{"data_stream":"string","index":"string"}}]}'

Create an enrich policy Added in 7.5.0

PUT /_enrich/policy/{name}
Api key auth Basic auth Bearer auth

Creates an enrich policy.

Path parameters

  • name string Required

    Name of the enrich policy to create or update.

Query parameters

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 /_enrich/policy/{name} 
curl \
 --request PUT 'http://api.example.com/_enrich/policy/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"additionalProperty1":{"enrich_fields":"string","indices":"string","match_field":"string","query":{},"name":"string","elasticsearch_version":"string"},"additionalProperty2":{"enrich_fields":"string","indices":"string","match_field":"string","query":{},"name":"string","elasticsearch_version":"string"}}'

Get lifecycle policies Added in 6.6.0

GET /_ilm/policy/{policy}
Api key auth Basic auth Bearer auth

Path parameters

  • policy string Required

    Identifier for the policy.

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.

  • timeout string

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

Responses

GET /_ilm/policy/{policy} 
curl \
 --request GET 'http://api.example.com/_ilm/policy/{policy}' \
 --header "Authorization: $API_KEY"
Response examples (200)
A successful response when retrieving a lifecycle policy. 
{
  "my_policy": {
    "version": 1,
    "modified_date": 82392349,
    "policy": {
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {
              "delete_searchable_snapshot": true
            }
          }
        }
      }
    },
    "in_use_by" : {
      "indices" : [],
      "data_streams" : [],
      "composable_templates" : []
    }
  }
}

Perform inference on the service Added in 8.11.0

POST /_inference/{inference_id}
Api key auth Basic auth Bearer auth

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.

Path parameters

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

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • text_embedding_bytes array[object]
      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]
      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]
      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]
      Hide completion attribute Show completion attribute object
    • rerank array[object]
      Hide rerank attributes Show rerank attributes object
POST /_inference/{inference_id} 
curl \
 --request POST 'http://api.example.com/_inference/{inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":"string","input":"string","task_settings":{}}'

Create an AlibabaCloud AI Search inference endpoint Added in 8.16.0

PUT /_inference/{task_type}/{alibabacloud_inference_id}
Api key auth Basic auth Bearer auth

Create an inference endpoint to perform an inference task with the alibabacloud-ai-search service.

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

Path parameters

  • task_type string Required

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

    Values are completion, rerank, space_embedding, or text_embedding.

  • alibabacloud_inference_id string Required

    The unique identifier of the inference endpoint.

application/json

Body

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

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

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

    • strategy string

      The chunking strategy: sentence or word.

  • service string Required

    Value is alibabacloud-ai-search.

  • service_settings object Required
    Hide service_settings attributes Show service_settings attributes object
    • api_key string Required

      A valid API key for the AlibabaCloud AI Search API.

    • host string Required

      The name of the host address used for the inference task. You can find the host address in the API keys section of the documentation.

      External documentation
    • rate_limit object
      Hide rate_limit attribute Show rate_limit attribute object
    • service_id string Required

      The name of the model service to use for the inference task. The following service IDs are available for the completion task:

      • ops-qwen-turbo
      • qwen-turbo
      • qwen-plus
      • qwen-max ÷ qwen-max-longcontext

      The following service ID is available for the rerank task:

      • ops-bge-reranker-larger

      The following service ID is available for the sparse_embedding task:

      • ops-text-sparse-embedding-001

      The following service IDs are available for the text_embedding task:

      ops-text-embedding-001 ops-text-embedding-zh-001 ops-text-embedding-en-001 ops-text-embedding-002

    • workspace string Required

      The name of the workspace used for the inference task.

  • task_settings object
    Hide task_settings attributes Show task_settings attributes object
    • input_type string

      For a sparse_embedding or text_embedding task, specify the type of input passed to the model. Valid values are:

      • ingest for storing document embeddings in a vector database.
      • search for storing embeddings of search queries run against a vector database to find relevant documents.
    • return_token boolean

      For a sparse_embedding task, it affects whether the token name will be returned in the response. It defaults to false, which means only the token ID will be returned in the response.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • chunking_settings 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).

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

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

      • strategy string

        The chunking strategy: sentence or word.

    • service string Required

      The service type

    • service_settings object Required
    • task_settings object
    • inference_id string Required

      The inference Id

    • task_type string Required

      Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.
PUT /_inference/{task_type}/{alibabacloud_inference_id} 
curl \
 --request PUT 'http://api.example.com/_inference/{task_type}/{alibabacloud_inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"service\": \"alibabacloud-ai-search\",\n    \"service_settings\": {\n        \"host\" : \"default-j01.platform-cn-shanghai.opensearch.aliyuncs.com\",\n        \"api_key\": \"AlibabaCloud-API-Key\",\n        \"service_id\": \"ops-qwen-turbo\",\n        \"workspace\" : \"default\"\n    }\n}"'
Request examples
Run `PUT _inference/completion/alibabacloud_ai_search_completion` to create an inference endpoint that performs a completion task. 
{
    "service": "alibabacloud-ai-search",
    "service_settings": {
        "host" : "default-j01.platform-cn-shanghai.opensearch.aliyuncs.com",
        "api_key": "AlibabaCloud-API-Key",
        "service_id": "ops-qwen-turbo",
        "workspace" : "default"
    }
}
Run `PUT _inference/rerank/alibabacloud_ai_search_rerank` to create an inference endpoint that performs a rerank task. 
{
    "service": "alibabacloud-ai-search",
    "service_settings": {
        "api_key": "AlibabaCloud-API-Key",
        "service_id": "ops-bge-reranker-larger",
        "host": "default-j01.platform-cn-shanghai.opensearch.aliyuncs.com",
        "workspace": "default"
    }
}
Run `PUT _inference/sparse_embedding/alibabacloud_ai_search_sparse` to create an inference endpoint that performs perform a sparse embedding task. 
{
    "service": "alibabacloud-ai-search",
    "service_settings": {
        "api_key": "AlibabaCloud-API-Key",
        "service_id": "ops-text-sparse-embedding-001",
        "host": "default-j01.platform-cn-shanghai.opensearch.aliyuncs.com",
        "workspace": "default"
    }
}
Run `PUT _inference/text_embedding/alibabacloud_ai_search_embeddings` to create an inference endpoint that performs a text embedding task. 
{
    "service": "alibabacloud-ai-search",
    "service_settings": {
        "api_key": "AlibabaCloud-API-Key",
        "service_id": "ops-text-embedding-001",
        "host": "default-j01.platform-cn-shanghai.opensearch.aliyuncs.com",
        "workspace": "default"
    }
}

Delete forecasts from a job Added in 6.5.0

DELETE /_ml/anomaly_detectors/{job_id}/_forecast
Api key auth Basic auth Bearer auth

By default, forecasts are retained for 14 days. You can specify a different retention period with the expires_in parameter in the forecast jobs API. The delete forecast API enables you to delete one or more forecasts before they expire.

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

Query parameters

  • allow_no_forecasts boolean

    Specifies whether an error occurs when there are no forecasts. In particular, if this parameter is set to false and there are no forecasts associated with the job, attempts to delete all forecasts return an error.

  • timeout string

    Specifies the period of time to wait for the completion of the delete operation. When this period of time elapses, the API fails and 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.
DELETE /_ml/anomaly_detectors/{job_id}/_forecast 
curl \
 --request DELETE 'http://api.example.com/_ml/anomaly_detectors/{job_id}/_forecast' \
 --header "Authorization: $API_KEY"
Response examples (200)
A successful response when deleting a forecast from an anomaly detection job. 
{
  "acknowledged": true
}

Run a watch

PUT /_watcher/watch/{id}/_execute
Api key auth Basic auth Bearer auth

This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing and debugging your watches prior to adding them to Watcher.

When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches. If your user is allowed to read index a, but not index b, then the exact same set of rules will apply during execution of a watch.

When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.

Path parameters

  • id string Required

    The watch identifier.

Query parameters

  • debug boolean

    Defines whether the watch runs in debug mode.

application/json

Body

  • action_modes object

    Determines how to handle the watch actions as part of the watch execution.

    Hide action_modes attribute Show action_modes attribute object
    • * string Additional properties

      Values are simulate, force_simulate, execute, force_execute, or skip.

  • alternative_input object

    When present, the watch uses this object as a payload instead of executing its own input.

    Hide alternative_input attribute Show alternative_input attribute object
    • * object Additional properties
  • ignore_condition boolean

    When set to true, the watch execution uses the always condition. This can also be specified as an HTTP parameter.

  • record_execution boolean

    When set to true, the watch record representing the watch execution result is persisted to the .watcher-history index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent runs. This can also be specified as an HTTP parameter.

  • simulated_actions object
    Hide simulated_actions attributes Show simulated_actions attributes object
  • trigger_data object
    Hide trigger_data attributes Show trigger_data attributes object

    • scheduled_time string | number Required

      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:
      DateTime string UnitMillis number

    • triggered_time 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:
      DateTime string UnitMillis number
  • watch object
    Hide watch attributes Show watch attributes object
    • actions object Required
      Hide actions attribute Show actions attribute object
    • condition object Required
      Hide condition attributes Show condition attributes object
      • always object
      • array_compare object
        Hide array_compare attribute Show array_compare attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
      • compare object
        Hide compare attribute Show compare attribute object
        • * object Additional properties
      • never object
      • script object
        Hide script attributes Show script attributes object

        • lang string

          Any of:
          ScriptLanguage string ScriptLanguage string

          Values are painless, expression, mustache, or java.

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

        • source string | object

          One of:
          ScriptSource string SearchRequestBody object
        • id string
    • input object Required
      Hide input attributes Show input attributes object
      • chain object
        Hide chain attribute Show chain attribute object
        • inputs array[object] Required
          Hide inputs attribute Show inputs attribute object
      • http object
        Hide http attributes Show http attributes object
        • extract array[string]
        • request object
          Hide request attributes Show request attributes object
          • auth object
            Hide auth attribute Show auth attribute object
          • body string
          • connection_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.

          • headers object
            Hide headers attribute Show headers attribute object
            • * string Additional properties
          • host string
          • method string

            Values are head, get, post, put, or delete.

          • params object
            Hide params attribute Show params attribute object
            • * string Additional properties
          • path string
          • port number
          • proxy object
            Hide proxy attributes Show proxy attributes object
          • read_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.

          • scheme string

            Values are http or https.

          • url string
        • response_content_type string

          Values are json, yaml, or text.

      • search object
        Hide search attributes Show search attributes object
        • extract array[string]
        • request object Required
          Hide request attributes Show request attributes object
          • body object
            Hide body attribute Show body attribute object
          • indices array[string]
          • indices_options object
            Hide indices_options attributes Show indices_options attributes object
            • 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.

            • expand_wildcards string | array[string]
            • ignore_unavailable boolean

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

            • ignore_throttled boolean

              If true, concrete, expanded or aliased indices are ignored when frozen.

          • search_type string

            Values are query_then_fetch or dfs_query_then_fetch.

          • template object
            Hide template attributes Show template attributes object
            • explain boolean
            • id string
            • params object
              Hide params attribute Show params attribute object
              • * object Additional properties
            • profile boolean
            • source string

              An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required.

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

      • simple object
        Hide simple attribute Show simple attribute object
        • * object Additional properties
    • metadata object
      Hide metadata attribute Show metadata attribute object
      • * object Additional properties
    • status object
      Hide status attributes Show status attributes object
    • throttle_period 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.

    • throttle_period_in_millis number

      Time unit for milliseconds

    • transform object
      Hide transform attributes Show transform attributes object
      • chain array[object]
      • script object
        Hide script attributes Show script attributes object
        • lang string
        • params object
          Hide params attribute Show params attribute object
          • * object Additional properties

        • source string | object

          One of:
          ScriptSource string SearchRequestBody object
        • id string
      • search object
        Hide search attributes Show search attributes object
        • request object Required
          Hide request attributes Show request attributes object
          • body object
            Hide body attribute Show body attribute object
          • indices array[string]
          • indices_options object
            Hide indices_options attributes Show indices_options attributes object
            • 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.

            • expand_wildcards string | array[string]
            • ignore_unavailable boolean

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

            • ignore_throttled boolean

              If true, concrete, expanded or aliased indices are ignored when frozen.

          • search_type string

            Values are query_then_fetch or dfs_query_then_fetch.

          • template object
            Hide template attributes Show template attributes object
            • explain boolean
            • id string
            • params object
              Hide params attribute Show params attribute object
              • * object Additional properties
            • profile boolean
            • source string

              An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required.

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

    • trigger object Required
      Hide trigger attribute Show trigger attribute object
      • schedule object
        Hide schedule attributes Show schedule attributes object
        • timezone string
        • cron string
        • daily object
          Hide daily attribute Show daily attribute object
        • hourly object
          Hide hourly attribute Show hourly attribute object
        • 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.

        • monthly object | array[object]

          One of:
          TimeOfMonth object array-2 array[object]
          Hide attributes Show attributes
          • at array[string] Required
          • on array[number] Required

        • weekly object | array[object]

          One of:
          TimeOfWeek object array-2 array[object]
          Hide attributes Show attributes
          • at array[string] Required
          • on array[string] Required

            Values are sunday, monday, tuesday, wednesday, thursday, friday, or saturday.

        • yearly object | array[object]

          One of:
          TimeOfYear object array-2 array[object]
          Hide attributes Show attributes
          • at array[string] Required
          • int array[string] Required

            Values are january, february, march, april, may, june, july, august, september, october, november, or december.

          • on array[number] Required

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required
    • watch_record object Required
      Hide watch_record attributes Show watch_record attributes object
      • condition object Required
        Hide condition attributes Show condition attributes object
        • always object
        • array_compare object
          Hide array_compare attribute Show array_compare attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
        • compare object
          Hide compare attribute Show compare attribute object
          • * object Additional properties
        • never object
        • script object
          Hide script attributes Show script attributes object

          • lang string

            Any of:
            ScriptLanguage string ScriptLanguage string

            Values are painless, expression, mustache, or java.

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

          • source string | object

            One of:
            ScriptSource string SearchRequestBody object
          • id string
      • input object Required
        Hide input attributes Show input attributes object
        • chain object
          Hide chain attribute Show chain attribute object
          • inputs array[object] Required
            Hide inputs attribute Show inputs attribute object
        • http object
          Hide http attributes Show http attributes object
          • extract array[string]
          • request object
            Hide request attributes Show request attributes object
            • auth object
              Hide auth attribute Show auth attribute object
            • body string
            • connection_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.

            • headers object
              Hide headers attribute Show headers attribute object
              • * string Additional properties
            • host string
            • method string

              Values are head, get, post, put, or delete.

            • params object
              Hide params attribute Show params attribute object
              • * string Additional properties
            • path string
            • port number
            • proxy object
              Hide proxy attributes Show proxy attributes object
            • read_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.

            • scheme string

              Values are http or https.

            • url string
          • response_content_type string

            Values are json, yaml, or text.

        • search object
          Hide search attributes Show search attributes object
          • extract array[string]
          • request object Required
            Hide request attributes Show request attributes object
            • body object
              Hide body attribute Show body attribute object
              • query object Required

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

            • indices array[string]
            • indices_options object
              Hide indices_options attributes Show indices_options attributes object
              • 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.

              • expand_wildcards string | array[string]
              • ignore_unavailable boolean

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

              • ignore_throttled boolean

                If true, concrete, expanded or aliased indices are ignored when frozen.

            • search_type string

              Values are query_then_fetch or dfs_query_then_fetch.

            • template object
              Hide template attributes Show template attributes object
              • explain boolean
              • id string
              • params object
              • profile boolean
              • source string

                An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required.

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

        • simple object
          Hide simple attribute Show simple attribute object
          • * object Additional properties
      • messages array[string] Required
      • metadata object
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • node string Required
      • result object Required
        Hide result attributes Show result attributes object
        • actions array[object] Required
          Hide actions attributes Show actions attributes object
        • condition object Required
          Hide condition attributes Show condition attributes object
          • met boolean Required
          • status string Required

            Values are success, failure, simulated, or throttled.

          • type string Required

            Values are always, never, script, compare, or array_compare.

        • execution_duration number

          Time unit for milliseconds

        • execution_time string | number Required

          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:
          DateTime string UnitMillis number
        • input object Required
          Hide input attributes Show input attributes object
          • payload object Required
            Hide payload attribute Show payload attribute object
            • * object Additional properties
          • status string Required

            Values are success, failure, simulated, or throttled.

          • type string Required

            Values are http, search, or simple.

      • state string Required

        Values are awaits_execution, checking, execution_not_needed, throttled, executed, failed, deleted_while_queued, or not_executed_already_queued.

      • trigger_event object Required
        Hide trigger_event attributes Show trigger_event attributes object
      • user string Required
      • watch_id string Required
      • status object
        Hide status attributes Show status attributes object
PUT /_watcher/watch/{id}/_execute 
curl \
 --request PUT 'http://api.example.com/_watcher/watch/{id}/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"trigger_data\" : { \n    \"triggered_time\" : \"now\",\n    \"scheduled_time\" : \"now\"\n  },\n  \"alternative_input\" : { \n    \"foo\" : \"bar\"\n  },\n  \"ignore_condition\" : true, \n  \"action_modes\" : {\n    \"my-action\" : \"force_simulate\" \n  },\n  \"record_execution\" : true \n}"'
Request examples
Run `POST _watcher/watch/my_watch/_execute` to run a watch. The input defined in the watch is ignored and the `alternative_input` is used as the payload. The condition as defined by the watch is ignored and is assumed to evaluate to true. The `force_simulate` action forces the simulation of `my-action`. Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being run normally. 
{
  "trigger_data" : { 
    "triggered_time" : "now",
    "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}
Run `POST _watcher/watch/my_watch/_execute` and set a different mode for each action. 
{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}
Run `POST _watcher/watch/_execute` to run a watch inline. All other settings for this API still apply when inlining a watch. In this example, while the inline watch defines a compare condition, during the execution this condition will be ignored. 
{
  "watch" : {
    "trigger" : { "schedule" : { "interval" : "10s" } },
    "input" : {
      "search" : {
        "request" : {
          "indices" : [ "logs" ],
          "body" : {
            "query" : {
              "match" : { "message": "error" }
            }
          }
        }
      }
    },
    "condition" : {
      "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
    },
    "actions" : {
      "log_error" : {
        "logging" : {
          "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
        }
      }
    }
  }
}
Response examples (200)
A successful response from `POST _watcher/watch/my_watch/_execute`. 
{
  "_id": "my_watch_0-2015-06-02T23:17:55.124Z", 
  "watch_record": { 
    "@timestamp": "2015-06-02T23:17:55.124Z",
    "watch_id": "my_watch",
    "node": "my_node",
    "messages": [],
    "trigger_event": {
      "type": "manual",
      "triggered_time": "2015-06-02T23:17:55.124Z",
      "manual": {
        "schedule": {
          "scheduled_time": "2015-06-02T23:17:55.124Z"
        }
      }
    },
    "state": "executed",
    "status": {
      "version": 1,
      "execution_state": "executed",
      "state": {
        "active": true,
        "timestamp": "2015-06-02T23:17:55.111Z"
      },
      "last_checked": "2015-06-02T23:17:55.124Z",
      "last_met_condition": "2015-06-02T23:17:55.124Z",
      "actions": {
        "test_index": {
          "ack": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "state": "ackable"
          },
          "last_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          },
          "last_successful_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          }
        }
      }
    },
    "input": {
      "simple": {
        "payload": {
          "send": "yes"
        }
      }
    },
    "condition": {
      "always": {}
    },
    "result": { 
      "execution_time": "2015-06-02T23:17:55.124Z",
      "execution_duration": 12608,
      "input": {
        "type": "simple",
        "payload": {
          "foo": "bar"
        },
        "status": "success"
      },
      "condition": {
        "type": "always",
        "met": true,
        "status": "success"
      },
      "actions": [
        {
          "id": "test_index",
          "index": {
            "response": {
              "index": "test",
              "version": 1,
              "created": true,
              "result": "created",
              "id": "AVSHKzPa9zx62AzUzFXY"
            }
          },
          "status": "success",
          "type": "index"
        }
      ]
    },
    "user": "test_admin" 
  }
}

Run a watch

POST /_watcher/watch/{id}/_execute
Api key auth Basic auth Bearer auth

This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing and debugging your watches prior to adding them to Watcher.

When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches. If your user is allowed to read index a, but not index b, then the exact same set of rules will apply during execution of a watch.

When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.

Path parameters

  • id string Required

    The watch identifier.

Query parameters

  • debug boolean

    Defines whether the watch runs in debug mode.

application/json

Body

  • action_modes object

    Determines how to handle the watch actions as part of the watch execution.

    Hide action_modes attribute Show action_modes attribute object
    • * string Additional properties

      Values are simulate, force_simulate, execute, force_execute, or skip.

  • alternative_input object

    When present, the watch uses this object as a payload instead of executing its own input.

    Hide alternative_input attribute Show alternative_input attribute object
    • * object Additional properties
  • ignore_condition boolean

    When set to true, the watch execution uses the always condition. This can also be specified as an HTTP parameter.

  • record_execution boolean

    When set to true, the watch record representing the watch execution result is persisted to the .watcher-history index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent runs. This can also be specified as an HTTP parameter.

  • simulated_actions object
    Hide simulated_actions attributes Show simulated_actions attributes object
  • trigger_data object
    Hide trigger_data attributes Show trigger_data attributes object

    • scheduled_time string | number Required

      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:
      DateTime string UnitMillis number

    • triggered_time 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:
      DateTime string UnitMillis number
  • watch object
    Hide watch attributes Show watch attributes object
    • actions object Required
      Hide actions attribute Show actions attribute object
    • condition object Required
      Hide condition attributes Show condition attributes object
      • always object
      • array_compare object
        Hide array_compare attribute Show array_compare attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
      • compare object
        Hide compare attribute Show compare attribute object
        • * object Additional properties
      • never object
      • script object
        Hide script attributes Show script attributes object

        • lang string

          Any of:
          ScriptLanguage string ScriptLanguage string

          Values are painless, expression, mustache, or java.

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

        • source string | object

          One of:
          ScriptSource string SearchRequestBody object
        • id string
    • input object Required
      Hide input attributes Show input attributes object
      • chain object
        Hide chain attribute Show chain attribute object
        • inputs array[object] Required
          Hide inputs attribute Show inputs attribute object
      • http object
        Hide http attributes Show http attributes object
        • extract array[string]
        • request object
          Hide request attributes Show request attributes object
          • auth object
            Hide auth attribute Show auth attribute object
          • body string
          • connection_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.

          • headers object
            Hide headers attribute Show headers attribute object
            • * string Additional properties
          • host string
          • method string

            Values are head, get, post, put, or delete.

          • params object
            Hide params attribute Show params attribute object
            • * string Additional properties
          • path string
          • port number
          • proxy object
            Hide proxy attributes Show proxy attributes object
          • read_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.

          • scheme string

            Values are http or https.

          • url string
        • response_content_type string

          Values are json, yaml, or text.

      • search object
        Hide search attributes Show search attributes object
        • extract array[string]
        • request object Required
          Hide request attributes Show request attributes object
          • body object
            Hide body attribute Show body attribute object
          • indices array[string]
          • indices_options object
            Hide indices_options attributes Show indices_options attributes object
            • 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.

            • expand_wildcards string | array[string]
            • ignore_unavailable boolean

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

            • ignore_throttled boolean

              If true, concrete, expanded or aliased indices are ignored when frozen.

          • search_type string

            Values are query_then_fetch or dfs_query_then_fetch.

          • template object
            Hide template attributes Show template attributes object
            • explain boolean
            • id string
            • params object
              Hide params attribute Show params attribute object
              • * object Additional properties
            • profile boolean
            • source string

              An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required.

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

      • simple object
        Hide simple attribute Show simple attribute object
        • * object Additional properties
    • metadata object
      Hide metadata attribute Show metadata attribute object
      • * object Additional properties
    • status object
      Hide status attributes Show status attributes object
    • throttle_period 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.

    • throttle_period_in_millis number

      Time unit for milliseconds

    • transform object
      Hide transform attributes Show transform attributes object
      • chain array[object]
      • script object
        Hide script attributes Show script attributes object
        • lang string
        • params object
          Hide params attribute Show params attribute object
          • * object Additional properties

        • source string | object

          One of:
          ScriptSource string SearchRequestBody object
        • id string
      • search object
        Hide search attributes Show search attributes object
        • request object Required
          Hide request attributes Show request attributes object
          • body object
            Hide body attribute Show body attribute object
          • indices array[string]
          • indices_options object
            Hide indices_options attributes Show indices_options attributes object
            • 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.

            • expand_wildcards string | array[string]
            • ignore_unavailable boolean

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

            • ignore_throttled boolean

              If true, concrete, expanded or aliased indices are ignored when frozen.

          • search_type string

            Values are query_then_fetch or dfs_query_then_fetch.

          • template object
            Hide template attributes Show template attributes object
            • explain boolean
            • id string
            • params object
              Hide params attribute Show params attribute object
              • * object Additional properties
            • profile boolean
            • source string

              An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required.

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

    • trigger object Required
      Hide trigger attribute Show trigger attribute object
      • schedule object
        Hide schedule attributes Show schedule attributes object
        • timezone string
        • cron string
        • daily object
          Hide daily attribute Show daily attribute object
        • hourly object
          Hide hourly attribute Show hourly attribute object
        • 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.

        • monthly object | array[object]

          One of:
          TimeOfMonth object array-2 array[object]
          Hide attributes Show attributes
          • at array[string] Required
          • on array[number] Required

        • weekly object | array[object]

          One of:
          TimeOfWeek object array-2 array[object]
          Hide attributes Show attributes
          • at array[string] Required
          • on array[string] Required

            Values are sunday, monday, tuesday, wednesday, thursday, friday, or saturday.

        • yearly object | array[object]

          One of:
          TimeOfYear object array-2 array[object]
          Hide attributes Show attributes
          • at array[string] Required
          • int array[string] Required

            Values are january, february, march, april, may, june, july, august, september, october, november, or december.

          • on array[number] Required

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required
    • watch_record object Required
      Hide watch_record attributes Show watch_record attributes object
      • condition object Required
        Hide condition attributes Show condition attributes object
        • always object
        • array_compare object
          Hide array_compare attribute Show array_compare attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
        • compare object
          Hide compare attribute Show compare attribute object
          • * object Additional properties
        • never object
        • script object
          Hide script attributes Show script attributes object

          • lang string

            Any of:
            ScriptLanguage string ScriptLanguage string

            Values are painless, expression, mustache, or java.

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

          • source string | object

            One of:
            ScriptSource string SearchRequestBody object
          • id string
      • input object Required
        Hide input attributes Show input attributes object
        • chain object
          Hide chain attribute Show chain attribute object
          • inputs array[object] Required
            Hide inputs attribute Show inputs attribute object
        • http object
          Hide http attributes Show http attributes object
          • extract array[string]
          • request object
            Hide request attributes Show request attributes object
            • auth object
              Hide auth attribute Show auth attribute object
            • body string
            • connection_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.

            • headers object
              Hide headers attribute Show headers attribute object
              • * string Additional properties
            • host string
            • method string

              Values are head, get, post, put, or delete.

            • params object
              Hide params attribute Show params attribute object
              • * string Additional properties
            • path string
            • port number
            • proxy object
              Hide proxy attributes Show proxy attributes object
            • read_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.

            • scheme string

              Values are http or https.

            • url string
          • response_content_type string

            Values are json, yaml, or text.

        • search object
          Hide search attributes Show search attributes object
          • extract array[string]
          • request object Required
            Hide request attributes Show request attributes object
            • body object
              Hide body attribute Show body attribute object
              • query object Required

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

            • indices array[string]
            • indices_options object
              Hide indices_options attributes Show indices_options attributes object
              • 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.

              • expand_wildcards string | array[string]
              • ignore_unavailable boolean

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

              • ignore_throttled boolean

                If true, concrete, expanded or aliased indices are ignored when frozen.

            • search_type string

              Values are query_then_fetch or dfs_query_then_fetch.

            • template object
              Hide template attributes Show template attributes object
              • explain boolean
              • id string
              • params object
              • profile boolean
              • source string

                An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required.

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

        • simple object
          Hide simple attribute Show simple attribute object
          • * object Additional properties
      • messages array[string] Required
      • metadata object
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • node string Required
      • result object Required
        Hide result attributes Show result attributes object
        • actions array[object] Required
          Hide actions attributes Show actions attributes object
        • condition object Required
          Hide condition attributes Show condition attributes object
          • met boolean Required
          • status string Required

            Values are success, failure, simulated, or throttled.

          • type string Required

            Values are always, never, script, compare, or array_compare.

        • execution_duration number

          Time unit for milliseconds

        • execution_time string | number Required

          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:
          DateTime string UnitMillis number
        • input object Required
          Hide input attributes Show input attributes object
          • payload object Required
            Hide payload attribute Show payload attribute object
            • * object Additional properties
          • status string Required

            Values are success, failure, simulated, or throttled.

          • type string Required

            Values are http, search, or simple.

      • state string Required

        Values are awaits_execution, checking, execution_not_needed, throttled, executed, failed, deleted_while_queued, or not_executed_already_queued.

      • trigger_event object Required
        Hide trigger_event attributes Show trigger_event attributes object
      • user string Required
      • watch_id string Required
      • status object
        Hide status attributes Show status attributes object
POST /_watcher/watch/{id}/_execute 
curl \
 --request POST 'http://api.example.com/_watcher/watch/{id}/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"trigger_data\" : { \n    \"triggered_time\" : \"now\",\n    \"scheduled_time\" : \"now\"\n  },\n  \"alternative_input\" : { \n    \"foo\" : \"bar\"\n  },\n  \"ignore_condition\" : true, \n  \"action_modes\" : {\n    \"my-action\" : \"force_simulate\" \n  },\n  \"record_execution\" : true \n}"'
Request examples
Run `POST _watcher/watch/my_watch/_execute` to run a watch. The input defined in the watch is ignored and the `alternative_input` is used as the payload. The condition as defined by the watch is ignored and is assumed to evaluate to true. The `force_simulate` action forces the simulation of `my-action`. Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being run normally. 
{
  "trigger_data" : { 
    "triggered_time" : "now",
    "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}
Run `POST _watcher/watch/my_watch/_execute` and set a different mode for each action. 
{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}
Run `POST _watcher/watch/_execute` to run a watch inline. All other settings for this API still apply when inlining a watch. In this example, while the inline watch defines a compare condition, during the execution this condition will be ignored. 
{
  "watch" : {
    "trigger" : { "schedule" : { "interval" : "10s" } },
    "input" : {
      "search" : {
        "request" : {
          "indices" : [ "logs" ],
          "body" : {
            "query" : {
              "match" : { "message": "error" }
            }
          }
        }
      }
    },
    "condition" : {
      "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
    },
    "actions" : {
      "log_error" : {
        "logging" : {
          "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
        }
      }
    }
  }
}
Response examples (200)
A successful response from `POST _watcher/watch/my_watch/_execute`. 
{
  "_id": "my_watch_0-2015-06-02T23:17:55.124Z", 
  "watch_record": { 
    "@timestamp": "2015-06-02T23:17:55.124Z",
    "watch_id": "my_watch",
    "node": "my_node",
    "messages": [],
    "trigger_event": {
      "type": "manual",
      "triggered_time": "2015-06-02T23:17:55.124Z",
      "manual": {
        "schedule": {
          "scheduled_time": "2015-06-02T23:17:55.124Z"
        }
      }
    },
    "state": "executed",
    "status": {
      "version": 1,
      "execution_state": "executed",
      "state": {
        "active": true,
        "timestamp": "2015-06-02T23:17:55.111Z"
      },
      "last_checked": "2015-06-02T23:17:55.124Z",
      "last_met_condition": "2015-06-02T23:17:55.124Z",
      "actions": {
        "test_index": {
          "ack": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "state": "ackable"
          },
          "last_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          },
          "last_successful_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          }
        }
      }
    },
    "input": {
      "simple": {
        "payload": {
          "send": "yes"
        }
      }
    },
    "condition": {
      "always": {}
    },
    "result": { 
      "execution_time": "2015-06-02T23:17:55.124Z",
      "execution_duration": 12608,
      "input": {
        "type": "simple",
        "payload": {
          "foo": "bar"
        },
        "status": "success"
      },
      "condition": {
        "type": "always",
        "met": true,
        "status": "success"
      },
      "actions": [
        {
          "id": "test_index",
          "index": {
            "response": {
              "index": "test",
              "version": 1,
              "created": true,
              "result": "created",
              "id": "AVSHKzPa9zx62AzUzFXY"
            }
          },
          "status": "success",
          "type": "index"
        }
      ]
    },
    "user": "test_admin" 
  }
}