---
layout: api
page_title: Evaluations - HTTP API
description: The /evaluation are used to query for and interact with evaluations.
---

# Evaluations HTTP API

The `/evaluation` endpoints are used to query for and interact with evaluations.

## List Evaluations

This endpoint lists all evaluations.

| Method | Path              | Produces           |
| ------ | ----------------- | ------------------ |
| `GET`  | `/v1/evaluations` | `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

- `prefix` `(string: "")`- Specifies a string to filter evaluations based on an
  ID prefix. Because the value is decoded to bytes, the prefix must have an
  even number of hexadecimal characters (0-9a-f). This is specified as a query
  string parameter and and is used before any `filter` expression is applied.

- `next_token` `(string: "")` - This endpoint supports paging. The
  `next_token` parameter accepts a string which is the `ID` field of
  the next expected evaluation. This value can be obtained from the
  `X-Nomad-NextToken` header from the previous response.

- `per_page` `(int: 0)` - Specifies a maximum number of evaluations to
  return for this request. If omitted, the response is not
  paginated. The `ID` of the last evaluation in the response can be
  used as the `last_token` of the next request to fetch additional
  pages.

- `filter` `(string: "")` - Specifies the [expression](/api-docs#filtering)
  used to filter the results. Consider using pagination or a query parameter to
  reduce resource used to serve the request.

- `job` `(string: "")` - Filter the list of evaluations to a specific
  job ID.

- `status` `(string: "")` - Filter the list of evaluations to a
  specific evaluation status (one of `blocked`, `pending`, `complete`,
  `failed`, or `canceled`).

- `namespace` `(string: "default")` - Specifies the target namespace.
  Specifying `*` will return all evaluations across all authorized namespaces.
  This parameter is used before any `filter` expression is applied.

- `reverse` `(bool: false)` - Specifies the list of returned evaluations should
  be sorted in the reverse order. By default evaluations are returned sorted in
  chronological order (older evaluations first), or in lexicographical order by
  their ID if the `prefix` query parameter is used.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/evaluations
```

```shell-session
$ curl \
    https://localhost:4646/v1/evaluations?prefix=25ba81
```

### Sample Response

```json
[
  {
    "ID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
    "Priority": 50,
    "Type": "service",
    "TriggeredBy": "job-register",
    "JobID": "example",
    "JobModifyIndex": 52,
    "NodeID": "",
    "NodeModifyIndex": 0,
    "Status": "complete",
    "StatusDescription": "",
    "Wait": 0,
    "NextEval": "",
    "PreviousEval": "",
    "BlockedEval": "",
    "FailedTGAllocs": null,
    "ClassEligibility": null,
    "EscapedComputedClass": false,
    "AnnotatePlan": false,
    "SnapshotIndex": 53,
    "QueuedAllocations": {
      "cache": 0
    },
    "CreateIndex": 53,
    "ModifyIndex": 55
  }
]
```

## Read Evaluation

This endpoint reads information about a specific evaluation by ID.

| Method | Path                      | Produces           |
| ------ | ------------------------- | ------------------ |
| `GET`  | `/v1/evaluation/:eval_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

- `:eval_id` `(string: <required>)`- Specifies the UUID of the evaluation. This
  must be the full UUID, not the short 8-character one. This is specified as
  part of the path.

- `related` `(bool: false)` - Specifies if related evaluations should be
  returned. Related evaluations are the ones that can be reached by following
  the trail of IDs for `NextEval`, `PreviousEval`, and `BlockedEval`. This is
  specified as a query parameter.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/evaluation/2deb5f06-a100-f01a-3316-5e501a4965e7?related=true
```

### Sample Response

```json
{
  "CreateIndex": 28,
  "CreateTime": 1647394818583344000,
  "FailedTGAllocs": {
    "cache": {
      "AllocationTime": 4111,
      "ClassExhausted": null,
      "ClassFiltered": null,
      "CoalescedFailures": 0,
      "ConstraintFiltered": null,
      "DimensionExhausted": null,
      "NodesAvailable": {
        "dc1": 0
      },
      "NodesEvaluated": 0,
      "NodesExhausted": 0,
      "NodesFiltered": 0,
      "QuotaExhausted": null,
      "ResourcesExhausted": null,
      "ScoreMetaData": null,
      "Scores": null
    }
  },
  "ID": "2deb5f06-a100-f01a-3316-5e501a4965e7",
  "JobID": "example",
  "ModifyIndex": 28,
  "ModifyTime": 1647394818583344000,
  "Namespace": "default",
  "PreviousEval": "0f98f7ea-59ae-4d90-d9bd-b8ce80b9e100",
  "Priority": 50,
  "RelatedEvals": [
    {
      "BlockedEval": "2deb5f06-a100-f01a-3316-5e501a4965e7",
      "CreateIndex": 27,
      "CreateTime": 1647394818582736000,
      "DeploymentID": "79ae0a49-acf6-0fcf-183f-8646f3167b88",
      "ID": "0f98f7ea-59ae-4d90-d9bd-b8ce80b9e100",
      "JobID": "example",
      "ModifyIndex": 30,
      "ModifyTime": 1647394818583565000,
      "Namespace": "default",
      "NextEval": "",
      "NodeID": "",
      "PreviousEval": "",
      "Priority": 50,
      "Status": "complete",
      "StatusDescription": "",
      "TriggeredBy": "node-drain",
      "Type": "service",
      "WaitUntil": null
    }
  ],
  "SnapshotIndex": 27,
  "Status": "blocked",
  "StatusDescription": "created to place remaining allocations",
  "TriggeredBy": "queued-allocs",
  "Type": "service"
}
```

## List Allocations for Evaluation

This endpoint lists the allocations created or modified for the given
evaluation.

| Method | Path                                  | Produces           |
| ------ | ------------------------------------- | ------------------ |
| `GET`  | `/v1/evaluation/:eval_id/allocations` | `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

- `:eval_id` `(string: <required>)`- Specifies the UUID of the evaluation. This
  must be the full UUID, not the short 8-character one. This is specified as
  part of the path.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/evaluation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/allocations
```

### Sample Response

```json
[
  {
    "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
    "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
    "Name": "example.cache[0]",
    "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
    "JobID": "example",
    "TaskGroup": "cache",
    "DesiredStatus": "run",
    "DesiredDescription": "",
    "ClientStatus": "running",
    "ClientDescription": "",
    "TaskStates": {
      "redis": {
        "State": "running",
        "Failed": false,
        "Events": [
          {
            "Type": "Received",
            "Time": 1495747371795703800,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          },
          {
            "Type": "Driver",
            "Time": 1495747371798867200,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": "Downloading image redis:3.2"
          },
          {
            "Type": "Started",
            "Time": 1495747379525667800,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          }
        ]
      }
    },
    "CreateIndex": 54,
    "ModifyIndex": 57,
    "CreateTime": 1495747371794276400
  }
]
```
