API Rate Limits

The Qualys API enforces limits on the API calls a customer can make based on their subscription settings. The limits apply to the use of all Qualys APIs except “auth” API (JWT Token Generation API). Default API control settings are provided by the service. Note these settings may be customized per subscription by Qualys Support.

The rate count and period are calculated dynamically each time an API call is received. The rate period represents a rolling window when API calls are counted.

API Controls Definition

• X-RateLimit-Remaining: This indicates the total API calls remaining in current rate limit window.
• X-RateLimit-ToWait-Sec: This time indicates the wait time for the rate limit to be reset. The customer has to wait for that time to execute next API calls.
• X-RateLimit-Window-Sec: This value indicates the total time window assigned for the APIs to be executed.
• X-RateLimit-Limit: This indicates the max number of API calls that can be executed in that particular rate limit window.

SampleSample 

curl -X POST -H "Accept: */*" -H "Authorization: Bearer <JWT Token>" -H "Content-Type: application/json" -i "https://gateway.qg1.apps.qualys.com/rest/2.0/count/am/asset"  
    

Provide "-i" in the curl request, as shown in the example, returns the response headers, which include the rate limit-related parameters.

After executing a curl request, check the following parameters in response headers to check the rate-limit status:

• X-RateLimit-Remaining: 0
• X-RateLimit-ToWait-Sec: 300
• X-RateLimit-Window-Sec: 3600
• X-RateLimit-Limit: 300

Example: A subscription for Standard API Service has the default API control settings. Consider that the API rate limit set for a customer is 300 API calls for a time window of 3600 seconds. If 300 API calls are received in a 5 minute period and none are blocked by any API limiting rules, then you need to wait 55 minutes before making the next call to the API. During the wait period, API calls will be blocked by the rate-limiting rule.

Sample HTTP Response HeadersSample HTTP Response Headers 

"Server":"nginx/1.19.1
Date":"Fri",
"16 Apr 2021 12":"29":"52 GMT
Content-Type":"application/json
Transfer-Encoding":"chunked
Connection":"keep-alive
Vary":"Accept-Encoding
X-RateLimit-Remaining":"4
X-RateLimit-Window-Sec":"100
X-RateLimit-Limit":"5
Vary":"Accept-Encoding
Cache-Control":"no-cache",
"no-store",
max-age=0,
"must-revalidate
Pragma":"no-cache
Expires":"0
X-Content-Type-Options":"nosniff
X-Frame-Options":"DENY
X-XSS-Protection":"1 ; mode=block
Referrer-Policy":"no-referrer"{
   "count":580,
   "responseCode":"SUCCESS",
   "responseMessage":"Valid API Access"
}

"Server":"nginx/1.19.1
Date":"Fri",
"16 Apr 2021 12":"29":"52 GMT
Content-Type":"application/json
Transfer-Encoding":"chunked
Connection":"keep-alive
Vary":"Accept-Encoding
X-RateLimit-Remaining":"4
X-RateLimit-Window-Sec":"100
X-RateLimit-Limit":"5
Vary":"Accept-Encoding
Cache-Control":"no-cache",
"no-store",
max-age=0,
"must-revalidate
Pragma":"no-cache
Expires":"0
X-Content-Type-Options":"nosniff
X-Frame-Options":"DENY
X-XSS-Protection":"1 ; mode=block
Referrer-Policy":"no-referrer"{
   "count":580,
   "responseCode":"SUCCESS",
   "responseMessage":"Valid API Access"
}