API Rate Limiting

The Qualys Container Security API is enforcing limits on the number of API calls a customer can make based on the API endpoint being called and the customer’s Qualys platform.

API rate limits are currently enforced for Gateway API calls made by customers on US Cloud Platform 2 (https://gateway.qg2.apps.qualys.com) and will be enforced on other Qualys platforms soon.

The API rate limits are enforced uniformly across all subscriptions on a particular platform. There currently is no ability to enforce custom rate limits for a given subscription.

How it works

When an API call is received, Qualys checks the rate limit defined for the API endpoint. If the rate limit has been exceeded the API call is blocked and an error is returned.

For each API we’ve defined the following settings:

Rate Limit Size (per API): The maximum number of API calls allowed within the subscription during the rate limit period. Provided in the response header ‘X-RateLimit-Limit’.
Rate Limit Period (in seconds, per API): The period of time that defines a window when API calls are counted within the subscription for each API. The window starts from the moment each API call is received by the service. Provided in the response header ‘X-RateLimit-Window-Sec’.
Rate Limit Remaining (per API): The remaining number of calls within the rate limit time period. Provided in the response header ‘X-RateLimit-Remaining’.

Rate limits defined per API endpoint

See the table below to understand the rate limits defined for Container Security API endpoints. Rate limits do not currently apply to the Container Runtime Security API.

API Endpoint Path (currently vxx = v1.2 or v1.3)	Rate Limit Size (max number of API calls)	Rate Limit Period (in seconds)	Description
/csapi/vxx/containers/list	120	60	Every 60 seconds, you can make 120 calls to the API.
/csapi/vxx/containers/**	5000	60	Every 60 seconds, you can make 5000 calls to the API
/csapi/vxx/images/list	120	60	Every 60 seconds, you can make 120 calls to the API.
/csapi/vxx/images/**	5000	60	Every 60 seconds, you can make 5000 calls to the API.
/csapi/vxx/registry/**	1000	60	Every 60 seconds, you can make 1000 calls to the API.
/csapi/vxx/sensors/**	1000	60	Every 60 seconds, you can make 1000 calls to the API.

**represents any API endpoint that matches this path unless otherwise noted

When the rate limit is reached

The API response “429 Too Many Requests” is returned anytime a user makes an API call and the rate limit for the API endpoint has already been reached. In other words, the rate limit size has already been reached for the rate limit period. Here’s an example:

API request

    curl -X GET
"https://gateway.qg2.apps.qualys.com/csapi/v1.3/images/list?limit=1" 
--header "Authorization: Bearer <token>"

Response

    Response header
HTTP/1.1 429 Too Many Requests
Server: nginx/1.19.1
Date: Thu, 17 Dec 2020 17:51:57 GMT
Content-Length: 0
Connection: keep-alive
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