OpenSearch/docs/reference/ml/df-analytics/apis/get-trained-models.asciidoc

[role="xpack"]
[testenv="basic"]
[[get-trained-models]]
= Get trained models API
[subs="attributes"]
++++
<titleabbrev>Get trained models</titleabbrev>
++++

Retrieves configuration information for a trained model.

experimental[]


[[ml-get-trained-models-request]]
== {api-request-title}

`GET _ml/trained_models/` +

`GET _ml/trained_models/<model_id>` +

`GET _ml/trained_models/_all` +

`GET _ml/trained_models/<model_id1>,<model_id2>` +

`GET _ml/trained_models/<model_id_pattern*>`


[[ml-get-trained-models-prereq]]
== {api-prereq-title}

If the {es} {security-features} are enabled, you must have the following
privileges:

* cluster: `monitor_ml`

For more information, see <<security-privileges>> and
{ml-docs-setup-privileges}.


[[ml-get-trained-models-desc]]
== {api-description-title}

You can get information for multiple trained models in a single API request by
using a comma-separated list of model IDs or a wildcard expression.


[[ml-get-trained-models-path-params]]
== {api-path-parms-title}

`<model_id>`::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]


[[ml-get-trained-models-query-params]]
== {api-query-parms-title}

`allow_no_match`::
(Optional, boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=allow-no-match-models]

`decompress_definition`::
(Optional, boolean)
Specifies whether the included model definition should be returned as a JSON map
(`true`) or in a custom compressed format (`false`). Defaults to `true`.

`for_export`::
(Optional, boolean)
Indicates if certain fields should be removed from the model configuration on
retrieval. This allows the model to be in an acceptable format to be retrieved
and then added to another cluster. Default is false.

`from`::
(Optional, integer)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=from-models]

`include`::
(Optional, string)
A comma delimited string of optional fields to include in the response body. The
default value is empty, indicating no optional fields are included. Valid
options are:
 - `definition`: Includes the model definition
 - `feature_importance_baseline`: Includes the baseline for {feat-imp} values.
 - `total_feature_importance`: Includes the total {feat-imp} for the training
   data set.
The baseline and total {feat-imp} values are returned in the `metadata` field
in the response body.

`size`::
(Optional, integer)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=size-models]

`tags`::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=tags]

[role="child_attributes"]
[[ml-get-trained-models-results]]
== {api-response-body-title}

`trained_model_configs`::
(array)
An array of trained model resources, which are sorted by the `model_id` value in
ascending order.
+
.Properties of trained model resources
[%collapsible%open]
====
`created_by`:::
(string)
Information on the creator of the trained model.

`create_time`:::
(<<time-units,time units>>)
The time when the trained model was created.

`default_field_map` :::
(object)
A string to string object that contains the default field map to use
when inferring against the model. For example, data frame analytics
may train the model on a specific multi-field `foo.keyword`.
The analytics job would then supply a default field map entry for
`"foo" : "foo.keyword"`.
+
Any field map described in the inference configuration takes precedence.

`estimated_heap_memory_usage_bytes`:::
(integer)
The estimated heap usage in bytes to keep the trained model in memory.

`estimated_operations`:::
(integer)
The estimated number of operations to use the trained model.

`license_level`:::
(string)
The license level of the trained model.

`metadata`:::
(object)
An object containing metadata about the trained model. For example, models
created by {dfanalytics} contain `analysis_config` and `input` objects.
+
.Properties of metadata
[%collapsible%open]
=====
`feature_importance_baseline`:::
(object)
An object that contains the baseline for {feat-imp} values. For {reganalysis},
it is a single value. For {classanalysis}, there is a value for each class.

`total_feature_importance`:::
(array)
An array of the total {feat-imp} for each feature used from
the training data set. This array of objects is returned if {dfanalytics} trained
the model and the request includes `total_feature_importance` in the `include`
request parameter.
+
.Properties of total {feat-imp}
[%collapsible%open]
======

`feature_name`:::
(string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-feature-name]

`importance`:::
(object)
A collection of {feat-imp} statistics related to the training data set for this particular feature.
+
.Properties of {feat-imp}
[%collapsible%open]
=======
`mean_magnitude`:::
(double)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-magnitude]

`max`:::
(int)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-max]

`min`:::
(int)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-min]

=======

`classes`:::
(array)
If the trained model is a classification model, {feat-imp} statistics are gathered
per target class value.
+
.Properties of class {feat-imp}
[%collapsible%open]

=======

`class_name`:::
(string)
The target class value. Could be a string, boolean, or number.

`importance`:::
(object)
A collection of {feat-imp} statistics related to the training data set for this particular feature.
+
.Properties of {feat-imp}
[%collapsible%open]
========
`mean_magnitude`:::
(double)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-magnitude]

`max`:::
(int)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-max]

`min`:::
(int)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-importance-min]

========

=======

======
=====

`model_id`:::
(string)
Idetifier for the trained model.

`tags`:::
(string)
A comma delimited string of tags. A trained model can have many tags, or none.

`version`:::
(string)
The {es} version number in which the trained model was created.
====

[[ml-get-trained-models-response-codes]]

== {api-response-codes-title}

`400`::
  If `include_model_definition` is `true`, this code indicates that more than
  one models match the ID pattern.

`404` (Missing resources)::
  If `allow_no_match` is `false`, this code indicates that there are no
  resources that match the request or only partial matches for the request.


[[ml-get-trained-models-example]]
== {api-examples-title}

The following example gets configuration information for all the trained models:

[source,console]
--------------------------------------------------
GET _ml/trained_models/
--------------------------------------------------
// TEST[skip:TBD]