elasticsearch/docs/reference/ml/df-analytics/apis/get-inference-trained-model.asciidoc

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

Retrieves configuration information for a trained model.

experimental[]


[[ml-get-inference-request]]
== {api-request-title}

`GET _ml/inference/` +

`GET _ml/inference/<model_id>` +

`GET _ml/inference/_all` +

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

`GET _ml/inference/<model_id_pattern*>`


[[ml-get-inference-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-inference-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-inference-path-params]]
== {api-path-parms-title}

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


[[ml-get-inference-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.
Valid options are:
 - `definition`: Includes the model definition
 - `total_feature_importance`: Includes the total feature importance for the
   training data set. This field is available in the `metadata` field in the
   response body.
Default is empty, indicating including no optional fields.

`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-inference-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]
=====
`total_feature_importance`:::
(array)
An array of the total feature importance 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 feature importance
[%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 feature importance statistics related to the training data set for this particular feature.
+
.Properties of feature importance
[%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, feature importance statistics are gathered
per target class value.
+
.Properties of class feature importance
[%collapsible%open]

=======

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

`importance`:::
(object)
A collection of feature importance statistics related to the training data set for this particular feature.
+
.Properties of feature importance
[%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)
Identifier 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-inference-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-inference-example]]
== {api-examples-title}

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

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