Elastic Stack (ELK Stack) ml anomaly API
The ml anomaly API from Elastic Stack (ELK Stack) — 45 operation(s) for ml anomaly.
The ml anomaly API from Elastic Stack (ELK Stack) — 45 operation(s) for ml anomaly.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/elk-stack-ml-anomaly-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Elasticsearch Request & Response Specification ml anomaly API
license:
name: Apache 2.0
url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
version: ''
tags:
- name: ml anomaly
paths:
/_ml/anomaly_detectors/{job_id}/_close:
post:
tags:
- ml anomaly
summary: Close anomaly detection jobs
description: 'A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.
When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.
If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.
When a datafeed that has a specified end date stops, it automatically closes its associated job.
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-close-job
parameters:
- in: path
name: job_id
description: Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. You can close multiple anomaly detection jobs in a single API request by using a group name, a comma-separated list of jobs, or a wildcard expression. You can close all jobs by using `_all` or by specifying `*` as the job identifier.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
- in: query
name: allow_no_match
description: 'Specifies what to do when the request: contains wildcard expressions and there are no jobs that match; contains the `_all` string or no identifiers and there are no matches; or contains wildcard expressions and there are only partial matches. By default, it returns an empty jobs 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.'
deprecated: false
schema:
default: true
type: boolean
style: form
- in: query
name: force
description: 'Use to close a failed job, or to forcefully close a job which has not responded to its initial close request; the request returns without performing the associated actions such as flushing buffers and persisting the model snapshots.
If you want the job to be in a consistent state after the close job API returns, do not set to `true`. This parameter should be used only in situations where the job has already failed or where you are not interested in results the job might have recently produced or might produce in the future.'
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: timeout
description: Controls the time to wait until a job has closed.
deprecated: false
schema:
default: 30m
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
requestBody:
content:
application/json:
schema:
type: object
properties:
allow_no_match:
description: Refer to the description for the `allow_no_match` query parameter.
default: true
type: boolean
force:
description: Refer to the descriptiion for the `force` query parameter.
default: false
type: boolean
timeout:
description: Refer to the description for the `timeout` query parameter.
default: 30m
allOf:
- $ref: '#/components/schemas/_types.Duration'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
closed:
type: boolean
required:
- closed
examples:
MlCloseJobResponseExample1:
description: A successful response when closing anomaly detection jobs.
value: "{\n \"closed\": true\n}"
x-state: Generally available; Added in 5.4.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
/_ml/calendars/{calendar_id}:
get:
tags:
- ml anomaly
summary: Get calendar configuration info
description: '
## Required authorization
* Cluster privileges: `monitor_ml`
'
operationId: ml-get-calendars-2
parameters:
- $ref: '#/components/parameters/ml.get_calendars-calendar_id'
- $ref: '#/components/parameters/ml.get_calendars-from'
- $ref: '#/components/parameters/ml.get_calendars-size'
requestBody:
$ref: '#/components/requestBodies/ml.get_calendars'
responses:
'200':
$ref: '#/components/responses/ml.get_calendars-200'
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
put:
tags:
- ml anomaly
summary: Create a calendar
description: '
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-put-calendar
parameters:
- in: path
name: calendar_id
description: A string that uniquely identifies a calendar.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
requestBody:
content:
application/json:
schema:
type: object
properties:
job_ids:
description: An array of anomaly detection job identifiers.
type: array
items:
$ref: '#/components/schemas/_types.Id'
description:
description: A description of the calendar.
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
calendar_id:
description: A string that uniquely identifies a calendar.
allOf:
- $ref: '#/components/schemas/_types.Id'
description:
description: A description of the calendar.
type: string
job_ids:
description: A list of anomaly detection job identifiers or group names.
allOf:
- $ref: '#/components/schemas/_types.Ids'
required:
- calendar_id
- job_ids
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
post:
tags:
- ml anomaly
summary: Get calendar configuration info
description: '
## Required authorization
* Cluster privileges: `monitor_ml`
'
operationId: ml-get-calendars-3
parameters:
- $ref: '#/components/parameters/ml.get_calendars-calendar_id'
- $ref: '#/components/parameters/ml.get_calendars-from'
- $ref: '#/components/parameters/ml.get_calendars-size'
requestBody:
$ref: '#/components/requestBodies/ml.get_calendars'
responses:
'200':
$ref: '#/components/responses/ml.get_calendars-200'
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
delete:
tags:
- ml anomaly
summary: Delete a calendar
description: 'Remove all scheduled events from a calendar, then delete it.
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-delete-calendar
parameters:
- in: path
name: calendar_id
description: A string that uniquely identifies a calendar.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/_types.AcknowledgedResponseBase'
examples:
MlDeleteCalendarResponseExample1:
description: A successful response when deleting a calendar.
value: "{\n \"acknowledged\": true\n}"
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
/_ml/calendars/{calendar_id}/events/{event_id}:
delete:
tags:
- ml anomaly
summary: Delete events from a calendar
operationId: ml-delete-calendar-event
parameters:
- in: path
name: calendar_id
description: A string that uniquely identifies a calendar.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
- in: path
name: event_id
description: 'Identifier for the scheduled event.
You can obtain this identifier by using the get calendar events API.'
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/_types.AcknowledgedResponseBase'
examples:
MlDeleteCalendarEventResponseExample1:
description: A successful response when deleting a calendar event.
value: "{\n \"acknowledged\": true\n}"
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
/_ml/calendars/{calendar_id}/jobs/{job_id}:
put:
tags:
- ml anomaly
summary: Add anomaly detection job to calendar
description: '
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-put-calendar-job
parameters:
- in: path
name: calendar_id
description: A string that uniquely identifies a calendar.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
- in: path
name: job_id
description: An identifier for the anomaly detection jobs. It can be a job identifier, a group name, or a comma-separated list of jobs or groups.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Ids'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
calendar_id:
description: A string that uniquely identifies a calendar.
allOf:
- $ref: '#/components/schemas/_types.Id'
description:
description: A description of the calendar.
type: string
job_ids:
description: A list of anomaly detection job identifiers or group names.
allOf:
- $ref: '#/components/schemas/_types.Ids'
required:
- calendar_id
- job_ids
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
delete:
tags:
- ml anomaly
summary: Delete anomaly jobs from a calendar
description: '
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-delete-calendar-job
parameters:
- in: path
name: calendar_id
description: A string that uniquely identifies a calendar.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
- in: path
name: job_id
description: 'An identifier for the anomaly detection jobs. It can be a job identifier, a group name, or a
comma-separated list of jobs or groups.'
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Ids'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
calendar_id:
description: A string that uniquely identifies a calendar.
allOf:
- $ref: '#/components/schemas/_types.Id'
description:
description: A description of the calendar.
type: string
job_ids:
description: A list of anomaly detection job identifiers or group names.
allOf:
- $ref: '#/components/schemas/_types.Ids'
required:
- calendar_id
- job_ids
examples:
MlDeleteCalendarJobResponseExample1:
description: A successful response when deleting an anomaly detection job from a calendar.
value: "{\n \"calendar_id\": \"planned-outages\",\n \"job_ids\": []\n}"
x-state: Generally available; Added in 6.2.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
/_ml/datafeeds/{datafeed_id}:
get:
tags:
- ml anomaly
summary: Get datafeeds configuration info
description: 'You can get information for multiple datafeeds in a single API request by
using a comma-separated list of datafeeds or a wildcard expression. You can
get information for all datafeeds by using `_all`, by specifying `*` as the
`<feed_id>`, or by omitting the `<feed_id>`.
This API returns a maximum of 10,000 datafeeds.
## Required authorization
* Cluster privileges: `monitor_ml`
'
operationId: ml-get-datafeeds
parameters:
- $ref: '#/components/parameters/ml.get_datafeeds-datafeed_id'
- $ref: '#/components/parameters/ml.get_datafeeds-allow_no_match'
- $ref: '#/components/parameters/ml.get_datafeeds-exclude_generated'
responses:
'200':
$ref: '#/components/responses/ml.get_datafeeds-200'
x-state: Generally available; Added in 5.5.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
put:
tags:
- ml anomaly
summary: Create a datafeed
description: 'Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job.
You can associate only one datafeed with each anomaly detection job.
The datafeed contains a query that runs at a defined interval (`frequency`).
If you are concerned about delayed data, you can add a delay (`query_delay'') at each interval.
By default, the datafeed uses the following query: `{"match_all": {"boost": 1}}`.
When Elasticsearch security features are enabled, your datafeed remembers which roles the user who created it had
at the time of creation and runs the query using those same roles. If you provide secondary authorization headers,
those credentials are used instead.
You must use Kibana, this API, or the create anomaly detection jobs API to create a datafeed. Do not add a datafeed
directly to the `.ml-config` index. Do not give users `write` privileges on the `.ml-config` index.
## Required authorization
* Index privileges: `read`
* Cluster privileges: `manage_ml`
'
operationId: ml-put-datafeed
parameters:
- in: path
name: datafeed_id
description: 'A numerical character string that uniquely identifies the datafeed.
This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores.
It must start and end with alphanumeric characters.'
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
- in: query
name: allow_no_indices
description: 'A setting that does two separate checks on the index expression.
If `false`, the request returns an error (1) if any wildcard expression
(including `_all` and `*`) resolves to zero matching indices or (2) if the
complete set of resolved indices, aliases or data streams is empty after all
expressions are evaluated. If `true`, index expressions that resolve to no
indices are allowed and the request returns an empty result.'
deprecated: false
schema:
default: true
type: boolean
style: form
- in: query
name: expand_wildcards
description: 'Type of index that wildcard patterns can match. If the request can target data streams, this argument determines
whether wildcard expressions match hidden data streams. Supports comma-separated values.'
deprecated: false
schema:
default: open
allOf:
- $ref: '#/components/schemas/_types.ExpandWildcards'
style: form
- in: query
name: ignore_throttled
description: If true, concrete, expanded, or aliased indices are ignored when frozen.
deprecated: true
schema:
default: true
type: boolean
style: form
- in: query
name: ignore_unavailable
description: 'If `false`, the request returns an error if it targets a concrete (non-wildcarded)
index, alias, or data stream that is missing, closed, or otherwise unavailable.
If `true`, unavailable concrete targets are silently ignored.'
deprecated: false
schema:
default: false
type: boolean
style: form
requestBody:
content:
application/json:
schema:
type: object
properties:
aggregations:
description: 'If set, the datafeed performs aggregation searches.
Support for aggregations is limited and should be used only with low cardinality data.'
type: object
additionalProperties:
$ref: '#/components/schemas/_types.aggregations.AggregationContainer'
chunking_config:
description: 'Datafeeds might be required to search over long time periods, for several months or years.
This search is split into time chunks in order to ensure the load on Elasticsearch is managed.
Chunking configuration controls how the size of these time chunks are calculated;
it is an advanced configuration option.'
allOf:
- $ref: '#/components/schemas/ml._types.ChunkingConfig'
delayed_data_check_config:
description: 'Specifies whether the datafeed checks for missing data and the size of the window.
The datafeed can optionally search over indices that have already been read in an effort to determine whether
any data has subsequently been added to the index. If missing data is found, it is a good indication that the
`query_delay` is set too low and the data is being indexed after the datafeed has passed that moment in time.
This check runs only on real-time datafeeds.'
allOf:
- $ref: '#/components/schemas/ml._types.DelayedDataCheckConfig'
frequency:
description: 'The interval at which scheduled queries are made while the datafeed runs in real time.
The default value is either the bucket span for short bucket spans, or, for longer bucket spans, a sensible
fraction of the bucket span. When `frequency` is shorter than the bucket span, interim results for the last
(partial) bucket are written then eventually overwritten by the full bucket results. If the datafeed uses
aggregations, this value must be divisible by the interval of the date histogram aggregation.'
allOf:
- $ref: '#/components/schemas/_types.Duration'
indices:
description: 'An array of index names. Wildcards are supported. If any of the indices are in remote clusters, the master
nodes and the machine learning nodes must have the `remote_cluster_client` role.'
allOf:
- $ref: '#/components/schemas/_types.Indices'
indices_options:
description: Specifies index expansion options that are used during search
allOf:
- $ref: '#/components/schemas/_types.IndicesOptions'
job_id:
description: Identifier for the anomaly detection job.
allOf:
- $ref: '#/components/schemas/_types.Id'
max_empty_searches:
description: 'If a real-time datafeed has never seen any data (including during any initial training period), it automatically
stops and closes the associated job after this many real-time searches return no documents. In other words,
it stops after `frequency` times `max_empty_searches` of real-time operation. If not set, a datafeed with no
end time that sees no data remains started until it is explicitly stopped. By default, it is not set.'
type: number
query:
description: 'The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an
Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this
object is passed verbatim to Elasticsearch.'
default: '{"match_all": {"boost": 1}}'
allOf:
- $ref: '#/components/schemas/_types.query_dsl.QueryContainer'
query_delay:
description: 'The number of seconds behind real time that data is queried. For example, if data from 10:04 a.m. might
not be searchable in Elasticsearch until 10:06 a.m., set this property to 120 seconds. The default
value is randomly selected between `60s` and `120s`. This randomness improves the query performance
when there are multiple jobs running on the same node.'
allOf:
- $ref: '#/components/schemas/_types.Duration'
runtime_mappings:
description: Specifies runtime fields for the datafeed search.
allOf:
- $ref: '#/components/schemas/_types.mapping.RuntimeFields'
script_fields:
description: 'Specifies scripts that evaluate custom expressions and returns script fields to the datafeed.
The detector configuration objects in a job can contain functions that use these script fields.'
type: object
additionalProperties:
$ref: '#/components/schemas/_types.ScriptField'
scroll_size:
description: 'The size parameter that is used in Elasticsearch searches when the datafeed does not use aggregations.
The maximum value is the value of `index.max_result_window`, which is 10,000 by default.'
default: 1000.0
type: number
headers:
x-state: Generally available; Added in 8.0.0
allOf:
- $ref: '#/components/schemas/_types.HttpHeaders'
examples:
MlPutDatafeedExample1:
description: An example body for a `PUT _ml/datafeeds/datafeed-test-job?pretty` request.
value: "{\n \"indices\": [\n \"kibana_sample_data_logs\"\n ],\n \"query\": {\n \"bool\": {\n \"must\": [\n {\n \"match_all\": {}\n }\n ]\n }\n },\n \"job_id\": \"test-job\"\n}"
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
aggregations:
type: object
additionalProperties:
$ref: '#/components/schemas/_types.aggregations.AggregationContainer'
authorization:
allOf:
- $ref: '#/components/schemas/ml._types.DatafeedAuthorization'
chunking_config:
allOf:
- $ref: '#/components/schemas/ml._types.ChunkingConfig'
delayed_data_check_config:
allOf:
- $ref: '#/components/schemas/ml._types.DelayedDataCheckConfig'
datafeed_id:
allOf:
- $ref: '#/components/schemas/_types.Id'
frequency:
allOf:
- $ref: '#/components/schemas/_types.Duration'
indices:
type: array
items:
type: string
job_id:
allOf:
- $ref: '#/components/schemas/_types.Id'
indices_options:
allOf:
- $ref: '#/components/schemas/_types.IndicesOptions'
max_empty_searches:
type: number
query:
allOf:
- $ref: '#/components/schemas/_types.query_dsl.QueryContainer'
query_delay:
allOf:
- $ref: '#/components/schemas/_types.Duration'
runtime_mappings:
allOf:
- $ref: '#/components/schemas/_types.mapping.RuntimeFields'
script_fields:
type: object
additionalProperties:
$ref: '#/components/schemas/_types.ScriptField'
scroll_size:
type: number
required:
- chunking_config
- datafeed_id
- indices
- job_id
- query
- query_delay
- scroll_size
x-state: Generally available; Added in 5.4.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
delete:
tags:
- ml anomaly
summary: Delete a datafeed
description: '
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-delete-datafeed
parameters:
- in: path
name: datafeed_id
description: 'A numerical character string that uniquely identifies the datafeed. This
identifier can contain lowercase alphanumeric characters (a-z and 0-9),
hyphens, and underscores. It must start and end with alphanumeric
characters.'
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.Id'
style: simple
- in: query
name: force
description: 'Use to forcefully delete a started datafeed; this method is quicker than
stopping and deleting the datafeed.'
deprecated: false
schema:
type: boolean
style: form
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/_types.AcknowledgedResponseBase'
examples:
MlDeleteDatafeedResponseExample1:
description: A successful response when deleting a datafeed.
value: "{\n \"acknowledged\": true\n}"
x-state: Generally available; Added in 5.4.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
/_ml/_delete_expired_data/{job_id}:
delete:
tags:
- ml anomaly
summary: Delete expired ML data
description: 'Delete all job results, model snapshots and forecast data that have exceeded
their retention days period. Machine learning state documents that are not
associated with any job are also deleted.
You can limit the request to a single or set of anomaly detection jobs by
using a job identifier, a group name, a comma-separated list of jobs, or a
wildcard expression. You can delete expired data for all anomaly detection
jobs by using `_all`, by specifying `*` as the `<job_id>`, or by omitting the
`<job_id>`.
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-delete-expired-data
parameters:
- $ref: '#/components/parameters/ml.delete_expired_data-job_id'
- $ref: '#/components/parameters/ml.delete_expired_data-requests_per_second'
- $ref: '#/components/parameters/ml.delete_expired_data-timeout'
requestBody:
$ref: '#/components/requestBodies/ml.delete_expired_data'
responses:
'200':
$ref: '#/components/responses/ml.delete_expired_data-200'
x-state: Generally available; Added in 5.4.0
x-metaTags:
- content: Elasticsearch, Machine Learning
name: product_name
/_ml/_delete_expired_data:
delete:
tags:
- ml anomaly
summary: Delete expired ML data
description: 'Delete all job results, model snapshots and forecast data that have exceeded
their retention days period. Machine learning state documents that are not
associated with any job are also deleted.
You can limit the request to a single or set of anomaly detection jobs by
using a job identifier, a group name, a comma-separated list of jobs, or a
wildcard expression. You can delete expired data for all anomaly detection
jobs by using `_all`, by specifying `*` as the `<job_id>`, or by omitting the
`<job_id>`.
## Required authorization
* Cluster privileges: `manage_ml`
'
operationId: ml-delete-expired-data-1
parameters:
- $ref: '#/components/parameters/ml.delete_expired_data-requests_per_second'
- $ref: '#/components/parameters/ml.delete_expired_data-timeout'
requestBody:
$ref: '#/components/requestBodies/ml.delete_expired_data'
responses:
'200':
$ref: '#/components/responses/ml.delete_expired_data-200'
x-sta
# --- truncated at 32 KB (702 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-ml-anomaly-api-openapi.yml