Managing Quotas Using REST

  • Updated on Jan 25, 2026
  • 3 minute(s) read
Prev Next

Introduction

VAST has a powerful REST API for accessing its administrative APIs. Please review the VAST REST API Overview first. In this example, we will show briefly how to manipulate quotas using the REST API. We will use curl to demonstrate how to do this. You can easily convert that to another programming language, such as Python, as shown in the Using Python with the REST API article.

Query Quotas

List all quotas

curl -u admin:123456 --insecure -X GET "https://10.100.12.201/api/quotas/" -H "accept: application/json" 

Get a specific quota

In this case, we will fetch just the quota with id 5.

curl -u admin:123456 --insecure -X GET "https://10.100.12.201/api/quotas/5/" -H "accept: application/json" 

That will result in a response like this:

{"id":5,"guid":"7526a41d-b6e7-4fc4-bfbc-9e3ac3096be3","name":"myquota","url":"https://10.100.121.201/api/quotas/1/","title":"keysquota","state":"OK","path":"/keystest/quotadir","grace_period":null,"soft_limit":null,"hard_limit":1000000000000,"soft_limit_inodes":0,"hard_limit_inodes":0,"used_inodes":3,"used_capacity":13832814592,"used_effective_capacity":13832814592,"used_capacity_tb":0.014,"used_effective_capacity_tb":0.014,"cluster":"se-perf","cluster_id":1,"tenant_id":1,"pretty_grace_period":null}

The interesting values in the response are:

  • soft_limit / hard_limit - soft and hard limit (in bytes) on how much can be written. When a soft limit is exceeded, an alert is raised. When a hard limit is exceeded, writes are blocked.  A default of 0 or null means do not enforce.

  • soft_limit_inodes / hard_limit_inodes - soft and hard limits on the number of files that can be created. The alerting and blocking behavior is the same as the previous.  A default of 0 means do not enforce.

  • grace_period - after this many seconds, a soft quota is enforced as if it were a hard quota. A default of 0 means do not enforce.

  • used_capacity - space logically used by files, considering their reported file sizes. Quotas are enforced against this prior to 3.2.1. There is also an _tb version of this that reports in TB for convenience.

  • used_effective_capacity - actual space consumed by files. This can be less than used_capacity if files are sparse.  Quota accounting is against this starting with 3.2.1. There is also a _tb version of this that reports in TB for convenience.

  • used_inodes - number of files created. Quotas are enforced against this.

 

Get a Specific Quota Using a Filter

Of course, you can also get a specific quota using a filter.

Filter by Name

In this example, we filter on the name, which is something you are more likely to know. Here we get the quota with the name testquota:

curl -u admin:123456 --insecure -X GET "https://10.100.121.201/api/quotas/?name=testquota" -H "accept: application/json"
[{"id":434592,"guid":"63b36bca-52bb-4f71-a168-3ba4269695c2","name":"testquota","url":"https://10.100.121.201/api/quotas/434592/","title":"testquota","state":"OK","path":"/testdir","grace_period":null,"soft_limit":500000000000,"hard_limit":5000000000000,"soft_limit_inodes":0,"hard_limit_inodes":0,"used_inodes":36,"sync_state":"SYNCHRONIZED","used_capacity":2109375000,"used_effective_capacity":2109375000,"used_capacity_tb":0.002,"pretty_state":"OK","used_effective_capacity_tb":0.002,"cluster":"seperf","cluster_id":1,"tenant_id":1,"pretty_grace_period":null,"pretty_grace_period_expiration":null,"time_to_block":null}]

Notice the internal identifier for this quota is 434592. Thus, it can be gotten using its internal ID by using:

curl -u admin:123456 --insecure -X GET "https://10.100.121.201/api/quotas/434592" -H "accept: application/json"
[{"id":434592,"guid":"63b36bca-52bb-4f71-a168-3ba4269695c2","name":"testquota","url":"https://10.100.121.201/api/quotas/434592/","title":"testquota","state":"OK","path":"/testdir","grace_period":null,"soft_limit":500000000000,"hard_limit":5000000000000,"soft_limit_inodes":0,"hard_limit_inodes":0,"used_inodes":36,"sync_state":"SYNCHRONIZED","used_capacity":2109375000,"used_effective_capacity":2109375000,"used_capacity_tb":0.002,"pretty_state":"OK","used_effective_capacity_tb":0.002,"cluster":"seperf","cluster_id":1,"tenant_id":1,"pretty_grace_period":null,"pretty_grace_period_expiration":null,"time_to_block":null}]

Filter by State

Sometimes it is useful to find quotas by synchronization state. There is a filter for that as well. In this example, we find all quotas that are failing to sync. This likely means that the directory the quota points to was removed.

curl -u admin:123456 --insecure -X GET "https://10.100.121.201/api/quotas/?sync_state=FAILED" -H "accept: application/json"

For those familiar with jq you can even parse this output and print just the id and name.

curl -u admin:123456 --insecure -X GET "https://10.100.121.201/api/quotas/" -H "accept: application/json" -s |jq '.[] | {id, name }'
{
"id": 1,
"name": "keystest1"
}
{
"id": 2,
"name": "keystest2"
}

or even just the id if you are thinking you want to examine those failed quotas:

curl -u admin:123456 --insecure -X GET "https://10.61.10.202/api/quotas/" -H "accept: application/json" -s |jq .[].id
1
2

Create a Quota

In addition to queries, you can create new quotas using the REST interface.  As you would expect, create operations using POST. What's a bit challenging is that the Swagger interface does not make clear what can be passed in to create a quota. If you want, you can figure this out by using a good browser's built-in debug tool - any command you execute in the VMS web interface is ultimately executed against the REST API, and a web debugger will show the parameters to the command.

Having said that, here's a specific example:

curl -u admin:123456 --insecure -X POST "https://10.100.12.201/api/quotas/" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"name\": \"newquota\", \"path\": \"/newdirwithquota\", \"hard_limit\": 50000000000, \"create_dir\": \"True\" }"

The hard limit set above by the way is 50 GB expressed as KB.

You may have noticed that create_dir was passed in with a true. This causes the system to create the directory along with the quota. If False was provided, it would require that the directory already existed and apply a quota to it.

Modifying an Existing Quota

An existing quota is easily modified by executing an HTTP PATCH request to the URL for the quota - remember the URL ends with the internal ID for the quota - in this example 434592.

Let's patch the previous example to increase the hard quota limit to 10 TB:

curl -u admin:123456 --insecure -X PATCH "https://10.100.121.201/api/quotas/434592/" -H "Content-Type: application/json" -d "{ \"hard_limit\": 10000000000000}"
{"id":434592,"guid":"63b36bca-52bb-4f71-a168-3ba4269695c2","name":"testquota","url":"https://10.100.121.201/api/quotas/434592/","title":"testquota","state":"OK","path":"/testdir","grace_period":null,"soft_limit":500000000000,"hard_limit":10000000000000,"soft_limit_inodes":0,"hard_limit_inodes":0,"used_inodes":36,"sync_state":"SYNCHRONIZED","used_capacity":2109375000,"used_effective_capacity":2109375000,"used_capacity_tb":0.002,"pretty_state":"OK","used_effective_capacity_tb":0.002,"cluster":"seperf","cluster_id":1,"tenant_id":1,"pretty_grace_period":null,"pretty_grace_period_expiration":null,"time_to_block":null}

 

Delete an Existing Quota

Deleting quotas is similar. Just use the DELETE HTTP request.

curl -u admin:123456 --insecure -X DELETE "https://10.100.121.201/api/quotas/434592/" -H "Content-Type: application/json"

Summary

Obviously, there are many more operations you can execute using the REST API in VAST. We will continue to provide more examples. If you have questions, let us know.

 

Related articles