---
layout: api
page_title: Quotas - HTTP API
description: The /quota endpoints are used to query for and interact with quotas.
---

# Quota HTTP API

The `/quota` endpoints are used to query for and interact with quotas.

<EnterpriseAlert product="nomad"/>

## List Quota Specifications

This endpoint lists all quota specifications.

| Method | Path         | Produces           |
| ------ | ------------ | ------------------ |
| `GET`  | `/v1/quotas` | `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                                                    |
| ---------------- | --------------------------------------------------------------- |
| `YES`            | `quota:read`<br />`namespace:*` if namespace has quota attached |

### Parameters

- `prefix` `(string: "")`- Specifies a string to filter quota specifications on
  based on an index prefix. This is specified as a query string parameter.

### Sample Request

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

```shell-session
$ curl \
    https://localhost:4646/v1/quotas?prefix=sha
```

### Sample Response

```json
[
  {
    "CreateIndex": 11,
    "Description": "Limit the shared default namespace",
    "Hash": "uTIBStF55xKqUMGdI23rdP+W+hsvZ2WEfRWU11j7CzQ=",
    "Limits": [
      {
        "Hash": "fTSnZHxUyDQcRT2Q7L3Hlu3vWpwSt0LWu7JVd3neK9k=",
        "Region": "global",
        "RegionLimit": {
          "CPU": 2500,
          "Cores": 0,
          "Devices": [
            {
              "Affinities": null,
              "Constraints": null,
              "Count": 1,
              "Name": "nvidia/gpu/Tesla M60"
            }
          ],
          "DiskMB": 0,
          "IOPS": 0,
          "MemoryMB": 2000,
          "MemoryMaxMB": 2000,
          "NUMA": null,
          "Networks": [
            {
              "CIDR": "",
              "Device": "",
              "DynamicPorts": null,
              "IP": "",
              "MBits": 50,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "SecretsMB": 0
        },
        "VariablesLimit": 1000
      }
    ],
    "ModifyIndex": 11,
    "Name": "default-quota"
  }
]
```

## Read Quota Specification

This endpoint reads information about a specific quota specification.

| Method | Path               | Produces           |
| ------ | ------------------ | ------------------ |
| `GET`  | `/v1/quota/:quota` | `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                                                    |
| ---------------- | --------------------------------------------------------------- |
| `YES`            | `quota:read`<br />`namespace:*` if namespace has quota attached |

### Parameters

- `:quota` `(string: <required>)`- Specifies the quota specification to query
  where the identifier is the quota's name.

### Sample Request

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

### Sample Response

```json
{
  "CreateIndex": 11,
  "Description": "Limit the shared default namespace",
  "Hash": "uTIBStF55xKqUMGdI23rdP+W+hsvZ2WEfRWU11j7CzQ=",
  "Limits": [
    {
      "Hash": "fTSnZHxUyDQcRT2Q7L3Hlu3vWpwSt0LWu7JVd3neK9k=",
      "Region": "global",
      "RegionLimit": {
        "CPU": 2500,
        "Cores": 0,
        "Devices": [
          {
            "Affinities": null,
            "Constraints": null,
            "Count": 1,
            "Name": "nvidia/gpu/Tesla M60"
          }
        ],
        "DiskMB": 0,
        "IOPS": 0,
        "MemoryMB": 2000,
        "MemoryMaxMB": 2000,
        "NUMA": null,
        "Networks": [
          {
            "CIDR": "",
            "Device": "",
            "DynamicPorts": null,
            "IP": "",
            "MBits": 50,
            "Mode": "",
            "ReservedPorts": null
          }
        ],
        "SecretsMB": 0
      },
      "VariablesLimit": 1000
    }
  ],
  "ModifyIndex": 11,
  "Name": "default-quota"
}
```

## Create or Update Quota Specification

This endpoint is used to create or update a quota specification.

| Method | Path                                  | Produces           |
| ------ | ------------------------------------- | ------------------ |
| `POST` | `/v1/quota/:quota` <br /> `/v1/quota` | `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`             | `quota:write` |

### Body

The request body contains a valid, JSON quota specification. View the api
package to see the definition of a [`QuotaSpec`
object](https://pkg.go.dev/github.com/hashicorp/nomad/api#QuotaSpec).

### Sample Payload

```javascript
{
  "Name": "default-quota",
  "Description": "Limit the shared default namespace",
  "Limits": [
    {
      "Region": "global",
      "RegionLimit": {
        "CPU": 2500,
        "MemoryMB": 2000,
        "MemoryMaxMB": 2000,
        "Devices": [
          {
            "Name": "nvidia/gpu/Tesla M60",
            "Count": 1
          }
        ],
        "VariablesLimit": 1000
      }
    }
  ]
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @spec.json \
    https://localhost:4646/v1/quota/shared-quota
```

```shell-session
$ curl \
    --request POST \
    --data @spec.json \
    https://localhost:4646/v1/quota
```

## Delete Quota Specification

This endpoint is used to delete a quota specification.

| Method   | Path               | Produces           |
| -------- | ------------------ | ------------------ |
| `DELETE` | `/v1/quota/:quota` | `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`             | `quota:write` |

### Parameters

- `:quota` `(string: <required>)`- Specifies the quota specification to delete
  where the identifier is the quota's name.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    https://localhost:4646/v1/quota/shared-quota
```

## List Quota Usages

This endpoint lists all quota usages.

| Method | Path               | Produces           |
| ------ | ------------------ | ------------------ |
| `GET`  | `/v1/quota-usages` | `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                                                    |
| ---------------- | --------------------------------------------------------------- |
| `YES`            | `quota:read`<br />`namespace:*` if namespace has quota attached |

### Parameters

- `prefix` `(string: "")`- Specifies a string to filter quota specifications on
  based on an index prefix. This is specified as a query string parameter.

### Sample Request

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

```shell-session
$ curl \
    https://localhost:4646/v1/quota-usages?prefix=sha
```

### Sample Response

```json
[
  {
    "Used": {
      "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc=": {
        "Region": "global",
        "RegionLimit": {
          "CPU": 500,
          "Cores": 0,
          "MemoryMB": 256,
          "MemoryMaxMB": 256,
          "DiskMB": 0,
          "IOPS": 0,
          "Networks": [
            {
              "CIDR": "",
              "Device": "",
              "DynamicPorts": null,
              "IP": "",
              "MBits": 50,
              "Mode": "",
              "ReservedPorts": null
            }
          ],
          "Devices": [
            {
              "Name": "nvidia/gpu/Tesla M60",
              "Count": 1,
              "Constraints": null,
              "Affinities": null
            }
          ],
          "NUMA": null,
          "SecretsMB": 0
        },
        "VariablesLimit": 0,
        "Hash": "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc="
      }
    },
    "Name": "default-quota",
    "CreateIndex": 11,
    "ModifyIndex": 38
  }
]
```

## Read Quota Usage

This endpoint reads information about a specific quota usage.

| Method | Path                     | Produces           |
| ------ | ------------------------ | ------------------ |
| `GET`  | `/v1/quota/usage/:quota` | `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                                                    |
| ---------------- | --------------------------------------------------------------- |
| `YES`            | `quota:read`<br />`namespace:*` if namespace has quota attached |

### Parameters

- `:quota` `(string: <required>)`- Specifies the quota specification to query
  where the identifier is the quota's name.

### Sample Request

```shell-session
$ curl \
    https://localhost:4646/v1/quota/usage/shared-quota
```

### Sample Response

```json
{
  "Used": {
    "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc=": {
      "Region": "global",
      "RegionLimit": {
        "CPU": 500,
        "Cores": 0,
        "MemoryMB": 256,
        "MemoryMaxMB": 256,
        "DiskMB": 0,
        "IOPS": 0,
        "Networks": [
          {
            "CIDR": "",
            "Device": "",
            "DynamicPorts": null,
            "IP": "",
            "MBits": 50,
            "Mode": "",
            "ReservedPorts": null
          }
        ],
        "Devices": [
          {
            "Name": "nvidia/gpu/Tesla M60",
            "Count": 1,
            "Constraints": null,
            "Affinities": null
          }
        ],
        "NUMA": null,
        "SecretsMB": 0
      },
      "VariablesLimit": 0,
      "Hash": "+kpaU440830Btn3/a0VUL4ROJCQyBOE55xwRR8rlFpc="
    }
  },
  "Name": "default-quota",
  "CreateIndex": 11,
  "ModifyIndex": 38
}
```