[DOCS] Move machine learning results definitions into APIs (#50257)

Author: lcawl

docs/reference/ml/anomaly-detection/apis/get-bucket.asciidoc

@@ -40,50 +40,133 @@ bucket.
 include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<timestamp>`::
-  (Optional, string) The timestamp of a single bucket result. If you do not
-  specify this parameter, the API returns information about all buckets.
+(Optional, string) The timestamp of a single bucket result. If you do not
+specify this parameter, the API returns information about all buckets.
 
 [[ml-get-bucket-request-body]]
 ==== {api-request-body-title}
 
 `anomaly_score`::
-  (Optional, double) Returns buckets with anomaly scores greater or equal than
-  this value.
+(Optional, double) Returns buckets with anomaly scores greater or equal than
+this value.
 
 `desc`::
-  (Optional, boolean) If true, the buckets are sorted in descending order.
+(Optional, boolean) If true, the buckets are sorted in descending order.
 
 `end`::
-  (Optional, string) Returns buckets with timestamps earlier than this time.
+(Optional, string) Returns buckets with timestamps earlier than this time.
 
 `exclude_interim`::
-  (Optional, boolean) If true, the output excludes interim results. By default,
-  interim results are included.
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=exclude-interim-results]
 
 `expand`::
-  (Optional, boolean) If true, the output includes anomaly records.
+(Optional, boolean) If true, the output includes anomaly records.
 
 `page`::
-`from`:::
-  (Optional, integer) Skips the specified number of buckets.
-`size`:::
-  (Optional, integer) Specifies the maximum number of buckets to obtain.
+`page`.`from`:::
+(Optional, integer) Skips the specified number of buckets.
+`page`.`size`:::
+(Optional, integer) Specifies the maximum number of buckets to obtain.
 
 `sort`::
-  (Optional, string) Specifies the sort field for the requested buckets. By
-  default, the buckets are sorted by the `timestamp` field.
+(Optional, string) Specifies the sort field for the requested buckets. By
+default, the buckets are sorted by the `timestamp` field.
 
 `start`::
-  (Optional, string) Returns buckets with timestamps after this time.
+(Optional, string) Returns buckets with timestamps after this time.
 
 [[ml-get-bucket-results]]
 ==== {api-response-body-title}
 
-The API returns the following information:
+The API returns an array of bucket objects, which have the following properties:
 
-`buckets`::
-  (array) An array of bucket objects. For more information, see
-  <<ml-results-buckets,Buckets>>.
+`anomaly_score`::
+(number) The maximum anomaly score, between 0-100, for any of the bucket
+influencers. This is an overall, rate-limited score for the job. All the anomaly 
+records in the bucket contribute to this score. This value might be updated as
+new data is analyzed.
+
+`bucket_influencers`::
+(array) An array of bucket influencer objects, which have the following
+properties:
+
+`bucket_influencers`.`anomaly_score`:::
+(number) A normalized score between 0-100, which is calculated for each bucket
+influencer. This score might be updated as newer data is analyzed.
+
+`bucket_influencers`.`bucket_span`:::
+(number) The length of the bucket in seconds. This value matches the `bucket_span`
+that is specified in the job.
+
+`bucket_influencers`.`initial_anomaly_score`:::
+(number) The score between 0-100 for each bucket influencer. This score is the
+initial value that was calculated at the time the bucket was processed.
+
+`bucket_influencers`.`influencer_field_name`:::
+(string) The field name of the influencer.
+
+`bucket_influencers`.`influencer_field_value`:::
+(string) The field value of the influencer. 
+
+`bucket_influencers`.`is_interim`:::
+(boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=is-interim]
+
+`bucket_influencers`.`job_id`:::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
+
+`bucket_influencers`.`probability`:::
+(number) The probability that the bucket has this behavior, in the range 0 to 1.
+This value can be held to a high precision of over 300 decimal places, so the
+`anomaly_score` is provided as a human-readable and friendly interpretation of
+this.
+
+`bucket_influencers`.`raw_anomaly_score`:::
+(number) Internal.
+
+`bucket_influencers`.`result_type`:::
+(string) Internal. This value is always set to `bucket_influencer`.
+
+`bucket_influencers`.`timestamp`:::
+(date) The start time of the bucket for which these results were calculated.
+
+`bucket_span`::
+(number)
+include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-span-results]
+
+`event_count`::
+(number) The number of input data records processed in this bucket.
+
+`initial_anomaly_score`::
+(number) The maximum `anomaly_score` for any of the bucket influencers. This is
+the initial value that was calculated at the time the bucket was processed.
+
+`is_interim`::
+(boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=is-interim]
+
+`job_id`::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
+
+`processing_time_ms`::
+(number) The amount of time, in milliseconds, that it took to analyze the
+bucket contents and calculate results.
+
+`result_type`::
+(string) Internal. This value is always set to `bucket`.
+
+`timestamp`::
+(date) The start time of the bucket. This timestamp uniquely identifies the
+bucket. 
++
+--
+NOTE: Events that occur exactly at the timestamp of the bucket are included in
+the results for the bucket.
+
+--
 
 [[ml-get-bucket-example]]
 ==== {api-examples-title}

docs/reference/ml/anomaly-detection/apis/get-category.asciidoc

@@ -28,7 +28,15 @@ privileges. See <<security-privileges>> and
 [[ml-get-category-desc]]
 ==== {api-description-title}
 
-For more information about categories, see
+When `categorization_field_name` is specified in the job configuration, it is
+possible to view the definitions of the resulting categories. A category
+definition describes the common terms matched and contains examples of matched
+values.
+
+The anomaly results from a categorization analysis are available as bucket,
+influencer, and record results. For example, the results might indicate that
+at 16:45 there was an unusual count of log message category 11. You can then
+examine the description and examples of that category. For more information, see
 {stack-ov}/ml-configuring-categories.html[Categorizing log messages].
 
 [[ml-get-category-path-parms]]
@@ -39,34 +47,55 @@ For more information about categories, see
 include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<category_id>`::
-  (Optional, long) Identifier for the category. If you do not specify this
-  parameter, the API returns information about all categories in the
-  {anomaly-job}.
+(Optional, long) Identifier for the category. If you do not specify this
+parameter, the API returns information about all categories in the {anomaly-job}.
 
 [[ml-get-category-request-body]]
 ==== {api-request-body-title}
 
 `page`::
-`from`:::
-  (Optional, integer) Skips the specified number of categories.
-`size`:::
-  (Optional, integer) Specifies the maximum number of categories to obtain.
+`page`.`from`:::
+(Optional, integer) Skips the specified number of categories.
+`page`.`size`:::
+(Optional, integer) Specifies the maximum number of categories to obtain.
 
 [[ml-get-category-results]]
 ==== {api-response-body-title}
 
-The API returns the following information:
+The API returns an array of category objects, which have the following properties:
 
-`categories`::
-  (array) An array of category objects. For more information, see
-  <<ml-results-categories,Categories>>.
+`category_id`::
+(unsigned integer) A unique identifier for the category.
+
+`examples`::
+(array) A list of examples of actual values that matched the category.
+
+`grok_pattern`::
+experimental[] (string) A Grok pattern that could be used in {ls} or an ingest 
+pipeline to extract fields from messages that match the category. This field is experimental and may be changed or removed in a future release. The Grok
+patterns that are found are not optimal, but are often a good starting point for
+manual tweaking.
+
+`job_id`::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
+
+`max_matching_length`::
+(unsigned integer) The maximum length of the fields that matched the category.
+The value is increased by 10% to enable matching for similar fields that have
+not been analyzed.
+
+`regex`::
+(string) A regular expression that is used to search for values that match the
+category.
+
+`terms`::
+(string) A space separated list of the common tokens that are matched in values
+of the category.
 
 [[ml-get-category-example]]
 ==== {api-examples-title}
 
-The following example gets information about one category for the
-`esxi_log` job:
-
 [source,console]
 --------------------------------------------------
 GET _ml/anomaly_detectors/esxi_log/results/categories
@@ -78,7 +107,6 @@ GET _ml/anomaly_detectors/esxi_log/results/categories
 --------------------------------------------------
 // TEST[skip:todo]
 
-In this example, the API returns the following information:
 [source,js]
 ----
 {