--- layout: api page_title: Recommendations - HTTP API sidebar_title: Recommendations description: >- The /recommendation endpoints are used to query for and interact with Dynamic Application Sizing recommendations. --- # Recommendation HTTP API The `/recommendation` endpoints are used to query and interact with Dynamic Application Sizing recommendations. ~> **Enterprise Only!** This API endpoint and functionality only exists in Nomad Enterprise. This is not present in the open source version of Nomad. ## List Recommendations This endpoint lists all the currently available recommendations and provides optional filtering of that list. | Method | Path | Produces | | ------ | --------------------- | ------------------ | | `GET` | `/v1/recommendations` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ----------------------------------------------------------------------------------- | | `YES` | `namespace:read-job` or `namespace:submit-recommendation` or `namespace:submit-job` | ### Parameters - `group` `(string: "")` - Specifies the task group name to filter within a job. If specified, the `job` parameter must also be specified. - `job` `(string: "")` - Specifies the job ID to filter the recommendations list by. - `namespace` `(string: "default")` - Specifies the namespace to search. Specifying `*` would return all recommendations across all the authorized namespaces. - `task` `(string: "")` - Specifies the task name to filter within a job and task group. If specified, the `job` and `group` query parameters must also be specified. ### Sample Request ```shell-session $ curl \ https://localhost:4646/v1/recommendations ``` ```shell-session $ curl \ https://localhost:4646/v1/recommendations?namespace=* ``` ```shell-session $ curl \ https://localhost:4646/v1/recommendations?namespace=*&job=example&group=cache&task=redis ``` ### Sample Response ```json [ { "ID": "cb80a13d-20d8-fb05-db3f-4ea0fe667b1b", "Region": "global", "Namespace": "default", "JobID": "example", "JobVersion": 0, "Group": "cache", "Task": "redis", "Resource": "MemoryMB", "Value": 10, "Current": 200, "Meta": { "nomad_autoscaler.count.capped": true, "nomad_autoscaler.count.original": 6, "nomad_autoscaler.reason_history": [], "nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c", "num_evaluated_windows": 1148, "window_size": 300000000000 }, "Stats": { "min": 2.6640625, "p99": 6.51171875, "max": 6.515625, "mean": 4.816847859995009 }, "EnforceVersion": false, "SubmitTime": 1603372587714807000, "CreateIndex": 5193, "ModifyIndex": 10437 }, { "ID": "fdd2b5f1-e6ad-110e-75b9-8f9410e1d8ab", "Region": "global", "Namespace": "default", "JobID": "example", "JobVersion": 0, "Group": "cache", "Task": "redis", "Resource": "CPU", "Value": 57, "Current": 500, "Meta": { "window_size": 300000000000, "nomad_policy_id": "b2c64295-4315-2fdc-6158-a27156808729", "num_evaluated_windows": 1117 }, "Stats": { "min": 0, "p99": 50, "max": 63.46186447143555, "mean": 0.3649455045779875 }, "EnforceVersion": false, "SubmitTime": 1603372287894356000, "CreateIndex": 5275, "ModifyIndex": 10419 } ] ``` ## Read Recommendation This endpoint reads information about a specific recommendation. | Method | Path | Produces | | ------ | --------------------------------------- | ------------------ | | `GET` | `/v1/recommendation/:recommendation_id` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | -------------------- | | `YES` | `namespace:read-job` | ### Parameters - `:recommendation_id` `(string: )`- Specifies the recommendation ID to query. This is specified as part of the path. ### Sample Request ```shell-session $ curl \ https://localhost:4646/v1/recommendation/cb80a13d-20d8-fb05-db3f-4ea0fe667b1b ``` ### Sample Response ```json { "ID": "cb80a13d-20d8-fb05-db3f-4ea0fe667b1b", "Region": "global", "Namespace": "default", "JobID": "example", "JobVersion": 0, "Group": "cache", "Task": "redis", "Resource": "MemoryMB", "Value": 10, "Current": 200, "Meta": { "nomad_autoscaler.count.original": 6, "nomad_autoscaler.reason_history": [], "nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c", "num_evaluated_windows": 1148, "window_size": 300000000000, "nomad_autoscaler.count.capped": true }, "Stats": { "min": 2.6640625, "p99": 6.51171875, "max": 6.515625, "mean": 4.816847859995009 }, "EnforceVersion": false, "SubmitTime": 1603372587714807000, "CreateIndex": 5193, "ModifyIndex": 10437 } ``` ## Apply and Dismiss Recommendations This endpoint is used to apply and dismiss recommendations. | Method | Path | Produces | | ------ | --------------------------- | ------------------ | | `POST` | `/v1/recommendations/apply` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `NO` | `namespace:submit-job` with `namespace:sentinel-override` if `PolicyOverride` set | ### Parameters - `Apply` `(array: nil)` - Specifies a set of recommendation IDs to be applied. This results in Nomad applying the recommendation to the job specification and performing a job register. - `Dismiss` `(array: nil)` - Specifies a set of recommendation IDs to be dismissed. This results in Nomad deleting them from the state store. - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies will be overridden. This allows a recommendation to be applied when it would be denied by a policy. ### Sample Payload ```json { "Apply": ["cb80a13d-20d8-fb05-db3f-4ea0fe667b1b"] } ``` ### Sample Request ```shell-session $ curl \ --request POST \ --data @payload.json \ https://localhost:4646/v1/recommendations/apply ``` ### Sample Response ```json { "Errors": [], "LastIndex": 0, "RequestTime": 0, "UpdatedJobs": [ { "EvalCreateIndex": 51, "EvalID": "3c91a755-f314-e2fb-500b-437ad08e13ea", "JobID": "example", "JobModifyIndex": 51, "Namespace": "default", "Recommendations": [ "cb80a13d-20d8-fb05-db3f-4ea0fe667b1b" ], "Warnings": "" } ] } ``` ## Create or Update a Recommendation This endpoint is used to create or update a recommendation. | Method | Path | Produces | | ------ | -------------------- | ------------------ | | `POST` | `/v1/recommendation` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ----------------------------------------------------------- | | `NO` | `namespace:submit-recommendation` or `namespace:submit-job` | ### Parameters - `ID` `(string: "")` - The ID of an existing recommendation to update. - `Region` `(string: "")`- The Nomad region identifier which contains the job that the recommendation is for. If omitted, this defaults to that of the Nomad agent. - `Namespace` `(string: "")`- The namespace within which the target job is running within. If omitted, this defaults to `default`. - `JobID` `(string: )`- The job ID which this recommendation is for. - `Group` `(string: )`- The task group name within the job which this recommendation is for. - `Task` `(string: )`- The task name within the task group which this recommendation is for. - `Resource` `(string: )`- The resource that the recommendation is for. Possible values are `CPU` and `MemoryMB`. - `Value` `(int: )`- The value recommendation for the resource. This must met the minimum requirements which are `1` for `CPU` and `10` for `MemoryMB`. - `Meta` `(map: nil)`- JSON block that is persisted as part of the recommendation providing arbitrary, useful information. - `Stats` `(map: nil)` - A mapping of statistics that are persisted as part of the recommendation providing insight into the recommendation calculation. - `EnforceVersion` `(bool: false)`- Indicates that the recommendation is only valid for the current version of the job. Subsequent job updates will automatically dismiss this recommendation. ### Sample Payload ```json { "Region": "global", "Namespace": "default", "JobID": "example", "Group": "cache", "Task": "redis", "Resource": "MemoryMB", "Value": 512, "Meta": { "nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c" }, "Stats": { "min": 2.6640625, "p99": 6.51171875, "max": 6.515625, "mean": 4.816847859995009 } } ``` ### Sample Request ```shell-session $ curl \ --request POST \ --data @payload.json \ https://localhost:4646/v1/recommendation ``` ### Sample Response ```json { "CreateIndex": 22, "Current": 256, "EnforceVersion": false, "Group": "cache", "ID": "47c97404-918f-8b19-873b-36d802f16f23", "JobID": "example", "JobVersion": 0, "Meta": { "nomad_policy_id": "c355d0ec-7aa1-2604-449d-4ec79c813d2c" }, "ModifyIndex": 25, "Namespace": "default", "Region": "global", "Resource": "MemoryMB", "Stats": { "mean": 4.816847859995009, "min": 2.6640625, "p99": 6.51171875, "max": 6.515625 }, "SubmitTime": 1603444202372926000, "Task": "redis", "Value": 512 } ```