When a query returns a large set of data, the results are returned in a series of pages. The client requests the next page after handling the data already received.

On large collections, performance degrades when retrieving the later pages. To avoid stress on the database server, restrict the size of data returned by the query by retrieving only the data you actually need:

• Filter the instances to be returned with a query clause. See query Clause: Restrict response by field values
• Retrieve only the fields you actually need by using a fields clause. See fields clause

Maximum Page Size

The maximum number of instances that can be returned in a page can be specified by the site parameter REST_API_PAGINATION_MAX_LIMIT. If the site parameter is not defined, the maximum instance count per page is 2000.

Default Page Size

The default number of instances returned in each page can be specified by the site parameter REST_API_PAGINATION_DEFAULT_LIMIT. If the site parameter is not defined, the default instance count per page is 100.

Specifying the Page Size in the Query

The client can indicate the number of instances to return in each page using the query parameter limit="n". For example:
/qcbin/api/domains/{domain}/projects/{project}/tests?limit=20

If the limit query parameter is greater than the maximum page size, an exception is thrown. The requested page size can be set equal to the maximum page size by specifying limit=max.

Specifying Where to Start a Page

The query parameter offset sets the first position to return from the results of the query. The default is 0, which starts the page at the first result. The syntax is offset=<offset>.

Example

Get three defects starting at the sixth result.

GET /qcbin/api/domains/my_domain/projects/REST/defects?limit=3 & offset=5