Batch Job Queue HTTP API

The Nomad /queue endpoints list the jobs in a node pool's batch job queue and read the tenant status of a dynamic priority queue. The nomad queue jobs and nomad queue status commands use these endpoints. Refer to Batch job queue for details about how queues work.

List Queued Jobs

This endpoint lists the jobs in the batch job queue of a node pool. The response includes jobs that are waiting in the queue and the job that the queue sent to the scheduler.

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

The response only includes jobs in namespaces where the token has the list-jobs capability.

Parameters

• node_pool (string: "") - Specifies the node pool whose queue to list. Specify this as a query string parameter. If omitted, the response has the passthrough type and an empty Workloads list.

• sort (string: "default") - Specifies the order of the jobs in the response. Set to priority to return jobs in queue order, which is the order that the queue sends them to the scheduler. Any other value returns jobs sorted by job ID. Specify this as a query string parameter.

• next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string that identifies the next expected job. Get this value from the X-Nomad-NextToken header of the last response.

• per_page (int: 0) - Specifies a maximum number of jobs to return for this request. If omitted, Nomad does not paginate the response. To fetch additional pages, use the value of the X-Nomad-NextToken header of the last response as the next_token of the next request.

Response

The Type field contains the queue type of the node pool, which is dynamic_priority, fifo, or passthrough. A node pool without a queue returns passthrough and an empty Workloads list.

Each object in Workloads contains the following fields for all queue types.

• JobID is the ID of the job.
• Namespace is the namespace of the job.
• Status is queued for a job that is waiting in the queue or placing for the job that the queue sent to the scheduler.
• Position is the job's position in the queue. The job that the queue sent to the scheduler has position 0.
• CreatedAt is the creation time of the job's evaluation, in nanoseconds since the Unix epoch.
• CreateIndex is the Raft index at which Nomad created the job's evaluation.

For a dynamic_priority queue, each object also contains the following fields.

• Tenant is the tenant of the job.
• AdjustedPriority is the priority that the queue uses to order the job.
• BasePriority is the job's priority.
• FairshareAdjustment, AgeAdjustment, CpuAdjustment, and MemoryAdjustment are the adjustments that the queue adds to the base priority. Refer to Adjusted priority for details.

Sample Request

$ nomad operator api '/v1/queue/jobs?node_pool=batch&sort=priority'

Sample Response

{
  "Index": 0,
  "KnownLeader": true,
  "LastContact": 0,
  "NextToken": "",
  "Type": "dynamic_priority",
  "Workloads": [
    {
      "AdjustedPriority": 61,
      "AgeAdjustment": 0,
      "BasePriority": 50,
      "CpuAdjustment": 4,
      "CreateIndex": 76,
      "CreatedAt": 1791927447090675000,
      "FairshareAdjustment": 0,
      "JobID": "team-a-job2",
      "MemoryAdjustment": 7,
      "Namespace": "team-a",
      "Position": 0,
      "Status": "placing",
      "Tenant": "team-a"
    },
    {
      "AdjustedPriority": 111,
      "AgeAdjustment": 0,
      "BasePriority": 50,
      "CpuAdjustment": 4,
      "CreateIndex": 80,
      "CreatedAt": 1791927448848244000,
      "FairshareAdjustment": 50,
      "JobID": "team-b-job1",
      "MemoryAdjustment": 7,
      "Namespace": "team-b",
      "Position": 1,
      "Status": "queued",
      "Tenant": "team-b"
    },
    {
      "AdjustedPriority": 111,
      "AgeAdjustment": 0,
      "BasePriority": 50,
      "CpuAdjustment": 4,
      "CreateIndex": 81,
      "CreatedAt": 1791927449713196000,
      "FairshareAdjustment": 50,
      "JobID": "team-b-job2",
      "MemoryAdjustment": 7,
      "Namespace": "team-b",
      "Position": 2,
      "Status": "queued",
      "Tenant": "team-b"
    },
    {
      "AdjustedPriority": 111,
      "AgeAdjustment": 0,
      "BasePriority": 50,
      "CpuAdjustment": 4,
      "CreateIndex": 82,
      "CreatedAt": 1791927450591141000,
      "FairshareAdjustment": 50,
      "JobID": "team-b-job3",
      "MemoryAdjustment": 7,
      "Namespace": "team-b",
      "Position": 3,
      "Status": "queued",
      "Tenant": "team-b"
    },
    {
      "AdjustedPriority": 61,
      "AgeAdjustment": 0,
      "BasePriority": 50,
      "CpuAdjustment": 4,
      "CreateIndex": 79,
      "CreatedAt": 1791927447969526000,
      "FairshareAdjustment": 0,
      "JobID": "team-a-job3",
      "MemoryAdjustment": 7,
      "Namespace": "team-a",
      "Position": 4,
      "Status": "queued",
      "Tenant": "team-a"
    }
  ]
}

Read Queue Status

This endpoint reads the status of the batch job queue of a node pool. For a dynamic priority queue, the status lists the tenants and their allocated resources.

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

Parameters

• node_pool (string: "default") - Specifies the node pool whose queue to inspect. Specify this as a query string parameter.

Response

The Type field contains the queue type of the node pool. Only a dynamic_priority queue returns a status. Other queue types return null for Status.

For a dynamic_priority queue, Status is a list of tenants. Each object in Status contains the following fields.

• TenantID is the tenant, which is a namespace or a job metadata value depending on the queue's tenant_type.
• TenantFairshare is the cpu in MHz and the memory in MB that Nomad allocated to the tenant's batch jobs in the node pool. Refer to Tenant fairshare for details.
• TotalFairshare is the cpu and memory allocated to all tenants in the queue.
• PercentageUsed is the tenant's share of the combined CPU and memory allocated to all tenants, as a whole number percentage.

Sample Request

$ nomad operator api '/v1/queue/status?node_pool=batch'

Sample Response

{
  "Index": 0,
  "KnownLeader": true,
  "LastContact": 0,
  "NextToken": "",
  "Status": [
    {
      "PercentageUsed": 100,
      "TenantFairshare": {
        "cpu": 600.0,
        "memory": 256.0
      },
      "TenantID": "team-a",
      "TotalFairshare": {
        "cpu": 600.0,
        "memory": 256.0
      }
    },
    {
      "PercentageUsed": 0,
      "TenantFairshare": {
        "cpu": 0.0,
        "memory": 0.0
      },
      "TenantID": "team-b",
      "TotalFairshare": {
        "cpu": 600.0,
        "memory": 256.0
      }
    }
  ],
  "Type": "dynamic_priority"
}