• Overview
    • Batch Processing Workloads
    • Edge Workload Management
    • Non-Containerized Application Orchestration
    • Simple Container Orchestration
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Plugins
  • Tools
  • Community
GitHub—Stars on GitHub
Download
    • v1.3.x (latest)
    • v1.2.x
    • v1.1.x
    • v1.0.x
    • v0.12.x
    • v0.11.x
  • HTTP API Overview

  • Libraries & SDKs
  • JSON Jobs

  • ACL Policies
  • ACL Tokens
  • Agent
  • Allocations
  • Client
  • Deployments
  • Evaluations
  • Events
  • Jobs
  • Namespaces
  • Nodes
  • Metrics
    • Overview
    • Autopilot
    • Raft
    • License
    • Scheduler
    • Snapshot
  • Plugins
  • Quotas
  • Recommendations
  • Regions
  • Scaling Policies
  • Search
  • Sentinel Policies
  • Services
  • Status
  • System
  • UI
  • Validate
  • Volumes
Type '/' to Search

»Evaluations HTTP API

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

»List Evaluations

This endpoint lists all evaluations.

MethodPathProduces
GET/v1/evaluationsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace: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 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

$ curl \
    https://localhost:4646/v1/evaluations
$ curl \
    https://localhost:4646/v1/evaluations
$ curl \
    https://localhost:4646/v1/evaluations?prefix=25ba81
$ curl \
    https://localhost:4646/v1/evaluations?prefix=25ba81

»Sample Response

[
  {
    "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
  }
]
[
  {
    "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.

MethodPathProduces
GET/v1/evaluation/:eval_idapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace: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

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

»Sample Response

{
  "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"
}
{
  "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.

MethodPathProduces
GET/v1/evaluation/:eval_id/allocationsapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
YESnamespace: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

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

»Sample Response

[
  {
    "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
  }
]
[
  {
    "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
  }
]
github logoEdit this page
DocsAPIResourcesPrivacySecurityPress KitConsent Manager