---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# PredictabilityEstimateVersion - Global

# PredictabilityEstimateVersion - Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 minutes to read

The PredictabilityEstimateVersion API is a scriptable object used in
Predictive Intelligence stores.

This API requires the Predictive Intelligence plugin (com.glide.platform_ml) and is provided within the `sn_ml` namespace.

Use this API when working with predictability estimate versions based on [PredictabilityEstimate API](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PredictabilityEstimateAPI "The PredictabilityEstimate API is a scriptable object used in Predictive Intelligence stores. This object provides estimation of how predictable fields of a dataset can be, and which features can be useful for predicting those fields.") objects in the [PredictabilityEstimate store](https://servicenow-prod.fluidtopics.net/CjCKNAt8AIxjXNKuZMSPpQ#PredictabilityEstimateStoreAPI "Enables storing and retrieving predictability estimates.").

The system activates the most recent version of the predictability estimate when it completes training, and only allows one version to be active at a time. However, you can activate any previously trained version you want to use to make predictions.  
Methods in this API are accessible using the following PredictabiltyEstimate methods:

* [getActiveVersion()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-getActiveVersion "Gets the active PredictabilityEstimateVersion object.")
* [getAllVersions()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-getAllVersions "Gets all versions of a predictability estimate.")
* [getLatestVersion()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-getLatestVersion "Gets the latest version of a predictability estimate.")
* [getVersion()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-getVersion_S "Gets a predictability estimate by provided version number.")
{#PredictabilityEstimateVersionAPI__ul_ycl_fzf_tlb}

## PredictabilityEstimateVersion - getProperties() {#ariaid-title2}

Gets predictability estimate object properties and version number.
{#PredictbltyEstV-getProperties__table_d2m_zwz_4lb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 1. Parameters]

{#PredictbltyEstV-getProperties__table_d2m_zwz_4lb} {#PredictbltyEstV-getProperties__table_e2m_zwz_4lb__entry__2}

| Type | Description |
|-|-|
| Object | Contents of the Dataset and [PredictabilityEstimate](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate.") version details. Results vary by object property setup. { "datasetProperties": {Object}, "domainName": "String", "inputFieldNames": [Array], "label": "String", "name": "String", "predictedFieldName": "String", "scope": "String", "trainingFrequency": "String", "versionNumber": "Number" } |
| \<Object\>.datasetProperties | Lists the properties of the [DatasetDefinition()](https://servicenow-prod.fluidtopics.net/5PRN6njd2wF_we1ri_egPw#DDef-DatasetDefinition_O "Creates an instance of the DatasetDefinition class, enabling you to define a dataset by table name, fields, and query.") object associated with the predictability estimate. { "encodedQuery": "String", "fieldDetails": [Array], "fieldNames": [Array], "tableName": "String" } Data type: Object. |
| \<Object\>.datasetProperties.tableName | Name of the table for the dataset. For example, `"tableName" : "Incident"`. Data type: String. |
| \<Object\>.datasetProperties.fieldNames | List of field names from the specified table as strings. For example, `"fieldNames" : ["short_description", "priority"]`. Data type: Array. |
| \<Object\>.datasetProperties.fieldNames.fieldDetails | List of JavaScript objects that specify field properties. [ { "name": "String", "type": "String" } ] Data type: Array. |
| \<Object\>.datasetProperties.fieldNames.fieldDetails.\<object\>.name | Name of the field defining the type of information to restrict this dataset to. Data type: String. |
| \<Object\>.datasetProperties.fieldDetails.\<object\>.type | Machine-learning field type. Data type: String. |
| \<Object\>.datasetProperties.fieldDetails.encodedQuery | Encoded query string in standard Glide format. See [Encoded query strings](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). Data type: String. |
| \<Object\>.domainName | Domain name associated with this dataset. See [Domain separation and Predictive Intelligence](https://www.servicenow.com/docs/access?context=domain-separation-predictive-intelligence&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US). Data type: String. |
| \<Object\>.inputFieldNames | List of candidate input fields as strings to be considered for estimation. Data type: String. |
| \<Object\>.isActive | Flag that indicates whether this version is active. Valid values: * true: Version is active. * false: Version is not active. {#PredictbltyEstV-getProperties__ul_i5m_lp1_dmb} Data type: String |
| \<Object\>.label | Identifies the prediction task. { "label": "my first prediction" } Data type: String. |
| \<Object\>.name | System-assigned name. Data type: String. |
| \<Object\>.predictedFieldName | Identifies a field to be trained for predictability. Data type: String. |
| \<Object\>.scope | Object scope. Currently the only valid value is `global`. Data type: String |
| \<Object\>.trainingFrequency | The frequency to retrain the model. Possible values: * every_30_days * every_60_days * every_90_days * every_120_days * every_180_days * run_once {#PredictbltyEstV-getProperties__ul_pmw_523_plb}Default: run_once Data type: String. |
| \<Object\>.versionNumber | Version number of the PredictabilityEstimate object. Data type: String. |
[Table 2. Returns]

{#PredictbltyEstV-getProperties__table_e2m_zwz_4lb}  
The following example gets properties of the active object
version in the store.

    // Get properties
    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_incident_categorization');

    gs.print(JSON.stringify(JSON.parse(mlEstimate.getActiveVersion().getProperties()), null, 2));

Output:

    "datasetProperties": {
        "encodedQuery": "activeANYTHING^EQ",
        "fieldNames": [
          "short_description",
          "category"
        ],
        "tableName": "incident"
      },
      "domainName": "global",
      "inputFieldNames": [
        "short_description"
      ],
      "isActive": "true",
      "label": "Incident Categorization_Trainer",
      "name": "ml_incident_categorization",
      "predictedFieldName": "category",
      "processingLanguage": "en",
      "stopwords": [
        "Default English Stopwords"
      ],
      "versionNumber": "1"
    }

## PredictabilityEstimateVersion - getResults() {#ariaid-title3}

Returns JSON results containing suggested input fields for an output field.
{#PredictbltyEstV-getResults__table_ytt_1xz_qlb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 3. Parameters]

{#PredictbltyEstV-getResults__table_ytt_1xz_qlb} {#PredictbltyEstV-getResults__table_ztt_1xz_qlb__entry__2}

| Type | Description |
|-|-|
| Object | JSON object results containing suggested input field options for an output field. |
| \<Object\>.\<output field name\> | Output field name, e.g., category, containing suggested input fields. { "<output field name>": { "nominalInputFields": [Array], "textInputFields": [Array] } } Data type: Object |
| \<Object\>.\<output field name\>.nominalInputFields | Nominal input field details. "nominalInputFields": [ { "fieldName": "String", "modelImprovement": "String" } ] Data type: Array. |
| \<Object\>.\<output field name\>.nominalInputFields.fieldName | Nominal input field name. Data type: String. |
| \<Object\>.\<output field name\>.nominalInputFields.modelImprovement | Score as a relative indication of how likely this field is to improve results. Data type: Number as a string. |
| \<Object\>.textInputFields | Text input field details. "textInputFields": [ { "fieldName": "String", "density": "String" } ] Data type: Array. |
| \<Object\>.textInputFields.fieldName | Text input field name. Data type: String. |
| \<Object\>.textInputFields.density | Value between 0 and 1.0 that represents frequency that the field is not empty. A value of 1.0 means that the field is not empty in all rows, and a value of 0 indicates that the field is empty in all rows. Data type: Number as a string. |
[Table 4. Returns]

{#PredictbltyEstV-getResults__table_ztt_1xz_qlb}  
The following example shows how to get results for a selected version of a predictability
estimate in the store.

    // Get results
    var estimateName = "ml_x_snc_global_global_predictability_estimate;"
    var mlEstimate = sn_ml.PredictabilityEstimateStore.get(estimateName);

    var results = mlEstimate.getActiveVersion().getResults();

    gs.print(JSON.stringify(JSON.parse(results), null, 2));

Output:

    {
      "category": {
        "nominalInputFields": [
          {
            "fieldName": "number",
            "modelImprovement": "0.167052396325189"
          },
          {
            "fieldName": "task_effective_number",
            "modelImprovement": "0.167052396325189"
          }
        ],
        "textInputFields": [
          {
            "fieldName": "short_description",
            "density": "1.0"
          }
        ]
      }
    }

## PredictabilityEstimateVersion - getStatus(Boolean includeDetails) {#ariaid-title4}

Gets training completion status.
{#PredictbltyEstV-getStatus_B__table_xfh_vbw_plb__entry__3}

| Name | Type | Description |
|-|-|-|
| includeDetails | Boolean | Flag that indicates whether to return status details. Valid values: * true: Return additional details. * false: Don't return additional details. {#PredictbltyEstV-getStatus_B__ul_n33_ckw_plb} Default: False |
[Table 5. Parameters]

{#PredictbltyEstV-getStatus_B__table_xfh_vbw_plb} {#PredictbltyEstV-getStatus_B__table_yfh_vbw_plb__entry__2}

| Type | Description |
|-|-|
| Object | JavaScript object containing training status information for a [PredictabilityEstimate](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PredictabilityEstimateAPI "The PredictabilityEstimate API is a scriptable object used in Predictive Intelligence stores. This object provides estimation of how predictable fields of a dataset can be, and which features can be useful for predicting those fields.") object. { "state": "String", "percentComplete": "Number as a String", "hasJobEnded": "Boolean value as a String", "details": {Object} } |
| \<Object\>.state | Training completion state. If the training job reaches a terminal state, the job does not leave that state. If the state is terminal, the hasJobEnded property is set to `true`. Possible values: * fetching_files_for_training * preparing_data * retry * solution_cancelled (terminal) * solution_complete (terminal) * solution_error (terminal) * solution_incomplete * training_request_received * training_request_timed_out (terminal) * training_solution * uploading_solution * waiting_for_training {#PredictbltyEstV-getStatus_B__ul_a5q_gh4_vlb} Data type: String |
| \<Object\>.hasJobEnded | Flag that indicates whether training is complete. Valid values: * true: Training is complete. * false: Training is incomplete. {#PredictbltyEstV-getStatus_B__ul_icy_zjx_rlb} Data type: Boolean value as a String |
| \<Object\>.percentComplete | Training percent complete. If the completion percentage is less than 100, the job might be in a terminal state. For example, if training times out. Data type: Number as a String Range: 0 thru 100 |
| \<Object\>.details | Object containing a list of additional training details. Data type: Object |
[Table 6. Returns]

{#PredictbltyEstV-getStatus_B__table_yfh_vbw_plb}  
The following example shows a successful result
with training complete.

    // Get status
    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_incident_categorization');

    gs.print(JSON.stringify(JSON.parse(mlEstimate.getActiveVersion().getStatus(true), null, 2)));

Output:

    {
     "state":"solution_complete",
     "percentComplete":"100",
     "hasJobEnded":"true",
     "details":{"stepLabel":"Solution Complete"} // This information is only returned if getStatus(true);
    }

The following example shows an unsuccessful
result with training complete.

    // Get status
    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_my_estimate_definition');
    var trainingStatus = mlEstimate.getLatestVersion().getStatus();

    gs.print(JSON.stringify(JSON.parse(trainingStatus), null, 2));

Output:

    {
      "state": "solution_complete",
      "percentComplete": "100",
      "hasJobEnded": "true"
    }

## PredictabilityEstimateVersion - getVersionNumber() {#ariaid-title5}

Gets the version number of a predictability estimate object.
{#PredictbltyEstV-getVersionNumber__table_jsz_sbw_plb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 7. Parameters]

{#PredictbltyEstV-getVersionNumber__table_jsz_sbw_plb} {#PredictbltyEstV-getVersionNumber__table_ksz_sbw_plb__entry__2}

| Type | Description |
|-|-|
| String | Version number. |
[Table 8. Returns]

{#PredictbltyEstV-getVersionNumber__table_ksz_sbw_plb}  
The following example shows how to get a version
number.

    // Get version number
    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

    gs.print("Version number: "+JSON.stringify(JSON.parse(mlEstimate.getActiveVersion().getVersionNumber()), null, 2));

Output:

    Version number: 1