---
layout: api
page_title: Scheduler - Operator - HTTP API
description: |-
The /operator/scheduler endpoints provide tools for management of Nomad server scheduler settings.
---
# Scheduler Operator HTTP API
The `/operator/scheduler` endpoints provide tools for management of Nomad server scheduler settings.
## Read Scheduler Configuration
This endpoint retrieves the latest Scheduler configuration. More options may be added in
the future.
| Method | Path | Produces |
| ------ | -------------------------------------- | ------------------ |
| `GET` | `/v1/operator/scheduler/configuration` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | --------------- |
| `NO` | `operator:read` |
### Sample Request
```shell-session
$ curl \
https://localhost:4646/v1/operator/scheduler/configuration
```
### Sample Response
```json
{
"Index": 5,
"KnownLeader": true,
"LastContact": 0,
"NextToken": "",
"SchedulerConfig": {
"CreateIndex": 5,
"MemoryOversubscriptionEnabled": false,
"ModifyIndex": 5,
"PauseEvalBroker": false,
"PreemptionConfig": {
"BatchSchedulerEnabled": false,
"ServiceSchedulerEnabled": false,
"SysBatchSchedulerEnabled": false,
"SystemSchedulerEnabled": true
},
"RejectJobRegistration": false,
"SchedulerAlgorithm": "binpack"
}
}
```
#### Field Reference
- `Index` `(int)` - The `Index` value is the Raft index corresponding to this
configuration.
- `SchedulerConfig` `(SchedulerConfig)` - The returned `SchedulerConfig` object has configuration
settings mentioned below.
- `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler
binpacks or spreads allocations on available nodes.
- `MemoryOversubscriptionEnabled` `(bool: false)` 1.1 Beta - When
`true`, tasks may exceed their reserved memory limit, if the client has excess
memory capacity. Tasks must specify [`memory_max`](/nomad/docs/job-specification/resources#memory_max)
to take advantage of memory oversubscription.
- `RejectJobRegistration` `(bool: false)` - When `true`, the server will return
permission denied errors for job registration, job dispatch, and job scale APIs,
unless the ACL token for the request is a management token. If ACLs are disabled,
no user will be able to register jobs. This allows operators to shed load from
automated processes during incident response.
- `PauseEvalBroker` `(bool: false)` - When set to `true`, the eval broker which
usually runs on the leader will be disabled. This will prevent the scheduler
workers from receiving new work.
- `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for various schedulers.
- `SystemSchedulerEnabled` `(bool: true)` - Specifies whether preemption for system jobs is enabled. Note that
this defaults to true.
- `SysBatchSchedulerEnabled` `(bool: false)` - Specifies whether preemption for system batch jobs is enabled. Note that
this defaults to false.
- `BatchSchedulerEnabled` `(bool: false)` - Specifies whether preemption for batch jobs is enabled. Note that
this defaults to false and must be explicitly enabled.
- `ServiceSchedulerEnabled` `(bool: false)` - Specifies whether preemption for service jobs is enabled. Note that
this defaults to false and must be explicitly enabled.
- `CreateIndex` - The Raft index at which the config was created.
- `ModifyIndex` - The Raft index at which the config was modified.
## Update Scheduler Configuration
This endpoint updates the scheduler configuration of the cluster.
| Method | Path | Produces |
| ------------- | -------------------------------------- | ------------------ |
| `PUT`, `POST` | `/v1/operator/scheduler/configuration` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ---------------- |
| `NO` | `operator:write` |
### Bootstrap Configuration Element
The [`default_scheduler_config`][] attribute of the server block will provide a
starting value for this configuration. Once bootstrapped, the value in the
server state is authoritative.
### Parameters
- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will
only happen if the given index matches the `ModifyIndex` of the configuration
at the time of writing.
### Sample Payload
```json
{
"SchedulerAlgorithm": "spread",
"MemoryOversubscriptionEnabled": false,
"RejectJobRegistration": false,
"PauseEvalBroker": false,
"PreemptionConfig": {
"SystemSchedulerEnabled": true,
"SysBatchSchedulerEnabled": false,
"BatchSchedulerEnabled": false,
"ServiceSchedulerEnabled": true
}
}
```
- `SchedulerAlgorithm` `(string: "binpack")` - Specifies whether scheduler
binpacks or spreads allocations on available nodes. Possible values are
`"binpack"` and `"spread"`
- `MemoryOversubscriptionEnabled` `(bool: false)` 1.1 Beta - When
`true`, tasks may exceed their reserved memory limit, if the client has excess
memory capacity. Tasks must specify [`memory_max`](/nomad/docs/job-specification/resources#memory_max)
to take advantage of memory oversubscription.
- `RejectJobRegistration` `(bool: false)` - When `true`, the server will return
permission denied errors for job registration, job dispatch, and job scale APIs,
unless the ACL token for the request is a management token. If ACLs are disabled,
no user will be able to register jobs. This allows operators to shed load from
automated processes during incident response.
- `PauseEvalBroker` `(bool: false)` - When set to `true`, the eval broker which
usually runs on the leader will be disabled. This will prevent the scheduler
workers from receiving new work.
- `PreemptionConfig` `(PreemptionConfig)` - Options to enable preemption for
various schedulers.
- `SystemSchedulerEnabled` `(bool: true)` - Specifies whether preemption for
system jobs is enabled. Note that if this is set to true, then system jobs
can preempt any other jobs.
- `SysBatchSchedulerEnabled` `(bool: false)` 1.2 - Specifies
whether preemption for system batch jobs is enabled. Note that if this is
set to true, then system batch jobs can preempt any other jobs.
- `BatchSchedulerEnabled` `(bool: false)` - Specifies
whether preemption for batch jobs is enabled. Note that if this is set to
true, then batch jobs can preempt any other jobs.
- `ServiceSchedulerEnabled` `(bool: false)` - Specifies
whether preemption for service jobs is enabled. Note that if this is set to
true, then service jobs can preempt any other jobs.
### Sample Response
```json
{
"Updated": false,
"Index": 15
}
```
- `Updated` - Indicates that the configuration was updated when a `cas` value is
provided. For non-CAS requests, this field will be false even though the
update is applied.
- `Index` - Current Raft index when the request was received.
[`default_scheduler_config`]: /nomad/docs/configuration/server#default_scheduler_config