open-nomad/website/pages/api-docs/recommendations.mdx

---
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: <required>)`- 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<string>: 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<string>: 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: <required>)`- The job ID which this recommendation is for.

- `Group` `(string: <required>)`- The task group name within the job which this
  recommendation is for.

- `Task` `(string: <required>)`- The task name within the task group which this
  recommendation is for.

- `Resource` `(string: <required>)`- The resource that the recommendation is for.
  Possible values are `CPU` and `MemoryMB`.

- `Value` `(int: <required>)`- The value recommendation for the resource. This
  must met the minimum requirements which are `1` for `CPU` and `10` for `MemoryMB`.

- `Meta` `(map<string|...>: nil)`- JSON block that is persisted as part of the
  recommendation providing arbitrary, useful information.

- `Stats` `(map<string|float64>: 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
}
```