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 for malware detection alerts of type behavioral.Step 1 - Search for malware detection alerts of type behavioral.

API request

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST"
--data-binary @- "https://qualysapi.qualys.com/qps/rest/1.0/search/md/detection/" < file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<ServiceRequest>
    <preferences>
        <limitResults>5</limitResults>
    </preferences>
    <filters>
        <Criteria field="type" operator="EQUALS">BEHAVIORAL</Criteria>
    </filters>
</ServiceRequest>

In the response, 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 alert records-->
    </data>
</ServiceResponse>

Step 2 - Search alerts and get next batch of resultsStep 2 - Search alerts 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 <lastId> 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 @-"https://qualysapi.qualys.com/ps/rest/1.0/search/md/detection/" < 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>
    <filters>
        <Criteria field="type"operator="EQUALS">BEHAVIORAL </Criteria>
        <Criteria field="id" operator="GREATER">123</Criteria>
    </filters>
</ServiceRequest>

Set 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>