{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":455,"path":"api-reference/rest-apis/agent-intelligence-api.md","title":"Predictive Intelligence API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Predictive Intelligence API\n\nThe Predictive Intelligence API provides endpoints that predict a field value based on one or more input fields and a trained solution.\n\nYou can only use this API when the Predictive Intelligence \\(com.glide.platform\\_ml\\) plugin is activated.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Predictive Intelligence - GET /agent\\_intelligence/solution/\\{solution\\_name\\}/prediction\n\nPredicts an output field value using a specific solution.\n\n### URL format\n\nDefault URL: `/api/now/agent_intelligence/solution/{solution_name}/prediction`\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsolution\\_name\n\n</td><td>\n\nName of solution to use for predictions. For example, `ml_incident_categorization`.Data type: String\n\n</td></tr></tbody>\n</table><table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nSolution definition input field key-value pair\n\n</td><td>\n\nName-value pair of the solution input field. For example, enter the name: `short_description` and the value: `Unable to connect to VPN`. Data type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nElement\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ninput\n\n</td><td>\n\nName-value pairs that were specified as input to the call.Data type: Object\n\n</td></tr><tr><td>\n\noutput\n\n</td><td>\n\nPredicted outcome values based on the specified solution.Data type: Object\n\n ```\n\"output\": {\n  \"confidence\": Number\",\n  \"outcome\": \"String\",\n  \"threshold\": Number\"\n}\n```\n\n</td></tr><tr><td>\n\noutput.confidence\n\n</td><td>\n\nEstimated precision of the prediction as a percentage. For example, **53.84615375762915**.Data type: Number\n\n</td></tr><tr><td>\n\noutput.outcome\n\n</td><td>\n\nPrediction output field value. For example, an incident categorization solution would return an incident category such as **inquiry**.Data type: String\n\n</td></tr><tr><td>\n\noutput.threshold\n\n</td><td>\n\nValue of the configured threshold associated with the prediction. Data type: Number\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"https://instance.service-now.com/api/now/predictive_intelligence/solution/ml_incident_categorization/prediction?short_description=unable%20to%20connect%20to%20VPN\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username\":\"password\"\n\n```\n\n```\n{\n  \"result\": {\n    \"input\": {\n      \"short_description\": \"unable to connect to VPN\",\n      \"api\": \"api\"\n    },\n    \"output\": {\n      \"outcome\": \"inquiry\",\n      \"confidence\": 53.84615375762915,\n      \"threshold\": 5\n    }\n  }\n}\n```\n\n## Predictive Intelligence - GET /agent\\_intelligence/solution/prediction\n\nReturns predictions for multiple solutions.\n\n**Note:** Outcome result objects are grouped by solution name and sys\\_id in the format `result.<solutionname>.<sys_id>.[{ <result1> },{ <result2>}]`.\n\nFor customization information, see [MLSolutionFactory scriptable objects](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/intelligent-experiences/using-ml-apis-mlsolutionfactory.md).\n\n### URL format\n\nVersioned URL: `/now/{api_version}/agent_intelligence/solution/prediction`\n\nDefault URL: `/now/agent_intelligence/solution/prediction`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n</td></tr></tbody>\n</table><table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nParameter\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ninput\\_filter\n\n</td><td>\n\nRequired parameter if **input\\_table** is used, don't use this parameter with **input\\_maps** parameter. Filter to select records on which to run predictions. For example:```\nsys_id 0ef47232db801300864adfea5e961912\n```\n\nData type: String\n\n</td></tr><tr><td>\n\ninput\\_maps\n\n</td><td>\n\nRequired unless using **input\\_table** parameter. Array of input name-value pairs. For example: ```\n[{\"short_description\":\"my email is not working\"}, {\"short_description\":\"need help with password\"}]\n```\n\nData type: Array of Objects\n\n</td></tr><tr><td>\n\ninput\\_table\n\n</td><td>\n\nRequired unless using **input\\_maps** parameter. Table name on which you want to run predictions. For example:```\nincident\n```\n\nData type: String\n\n</td></tr><tr><td>\n\noptions\n\n</td><td>\n\nJSON object with optional arguments. For example:```\n{\"top_n\" : 5, \"apply_threshold\":false}\n```\n\nValid options:\n\n-   top\\_n: Number. If provided, returns the top results, up to the specified number of predictions.\n-   apply\\_threshold: Boolean. Checks the threshold value for the solution and applies it to the result set. The threshold value is solution threshold for similarity or class-level threshold for classification. Default value is true.\n-   custom\\_results\\_filter: String. Similarity solutions only. Specifies the allowed set from which results are returned using an encoded query.\n\nData type: Object\n\n</td></tr><tr><td>\n\nsolution\\_names\n\n</td><td>\n\nRequired. Comma-separated list of solution names for which you want to run predictions. For example:```\nml_incident_categorization,ml_incident_assignment\n```\n\nData type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|404|Not found. The requested item wasn't found.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nElement\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nconfidence\n\n</td><td>\n\nValue of the confidence associated with the prediction. For example, 53.84. Data type: Number\n\n</td></tr><tr><td>\n\npredictedSysId\n\n</td><td>\n\nThe sys\\_id of the predicted value. Results can be from any table on which information is being predicted. Data type: String\n\n</td></tr><tr><td>\n\npredictedValue\n\n</td><td>\n\nValue representing the prediction result. Data type: String\n\n</td></tr><tr><td>\n\nthreshold\n\n</td><td>\n\nValue of the configured threshold associated with the prediction. Data type: Number\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"http://instance.servicenow.com/api/now/agent_intelligence/solution/prediction?input_table=incident&input_filter=sys_id%3D0ef47232db801300864adfea5e961912&solution_names=ml_incident_categorization%2Cml_incident_assignment&options=%7B%22top_n%22%20%3A%202%2C%20%22apply_threshold%22%3Afalse%7D\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username\":\"password\"\n```\n\n```\n{\n  \"result\": {\n    \"ml_incident_categorization\": {\n      \"0ef47232db801300864adfea5e961912\": [\n        {\n          \"confidence\": 29.12211732875455,\n          \"threshold\": 15,\n          \"predictedValue\": \"Email\",\n          \"predictedSysId\": \"\"\n        },\n        {\n          \"confidence\": 19.08583525847071,\n          \"threshold\": 14,\n          \"predictedValue\": \"Platform Performance\",\n          \"predictedSysId\": \"\"\n        }\n      ]\n    },\n    \"ml_incident_assignment\": {\n      \"0ef47232db801300864adfea5e961912\": [\n        {\n          \"confidence\": 5.782322543467415,\n          \"threshold\": 5,\n          \"predictedValue\": \"IT Finance CAB\",\n          \"predictedSysId\": \"5f63e48fc0a8010e00eeaad81cd4dd37\"\n        },\n        {\n          \"confidence\": 5.303589009246953,\n          \"threshold\": -1,\n          \"predictedValue\": \"NY DB\",\n          \"predictedSysId\": \"5f74727dc0a8010e01efe33a251993f9\"\n        }\n      ]\n    }\n  }\n}\n\n```\n\n"}}