Output Pagination and Truncation
The XML output of a search API request is paginated and the default page size is 100 object records. The page size can be customized to a value between 1 and 1,000. If the number of records is greater than the page size then the <ServiceResponse> element shows the response code SUCCESS with the element <hasMoreRecords>true</hasMoreRecords> as shown below.
Follow the simple process below to obtain the first two the XML pages for an API request. Please apply the same logic to get all the next (n+1) pages until all records are returned. This is indicated when <hasMoreRecords>false</hasMoreRecords>.
Step 1 - Search alerts and get first batch of resultsStep 1 - Search alerts and get first batch of results
Search for assets that have a name containing the string “Windows”.
API request
curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/rest/2.0/search/am/hostasset” < file.xml
Note: “file.xml” contains the request POST data.
Request POST data
<ServiceRequest>
<preferences>
<limitResults>5</limitResults>
</preferences>
<filters>
<Criteria field="tagName" operator="EQUALS">Cloud Agent
</Criteria>
<Criteria field="name"operator="CONTAINS">Windows
</Criteria>
</filters>
</ServiceRequest>
The number of records is greater than the default pagination value so the <ServiceResponse> element identifies the last ID of the object in the current page output.
Response
<ServiceResponse ...>
<responseCode>SUCCESS</responseCode>
<COUNT>5</COUNT>
<hasMoreRecords>true</hasMoreRecords>
<lastId>123</lastId>
<data>
<!--here you will find 5 asset records-->
</data>
</ServiceResponse>
Step 2 - Search assets and get next batch of resultsStep 2 - Search assets and get next batch of results
To get the next page of results, you need to edit your service request in “file.xml” that will be passed to API request as a POST payload. According to the element returned in the first page, you want the next page of results to start with the object ID 124 or greater.
API request
curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/qps/rest/2.0/search/am/hostasset" < file.xml
Note: “file.xml” contains the request POST data.
You’ll notice the operator field value is set to 123, which is the value returned in <lastId> of the previous page output. The GREATER operator is a logical “greater than” (it does not mean greater than or equal to).
Request POST data
<ServiceRequest>
<preferences>
<limitResults>5</limitResults>
</preferences>
<filters>
<Criteria field="name" operator="CONTAINS">Windows</Criteria>
<Criteria field="id" operator="GREATER">123</Criteria>
<Criteria field="tagName" operator="EQUALS">Cloud Agent
</Criteria>
</filters>
</ServiceRequest>
Set custom page sizeSet custom page size
The service request needs to contain the <preferences> section with the <limitResults> parameter. For the <limitResults> parameter you can enter a value from 1 to 1,000.
Response
<ServiceRequest>
<filters>
<Criteria> ... </Criteria>
</filters>
<preferences>
<limitResults>200</limitResults>
</preferences>
</ServiceRequest>