Page data (limit, offset, total_count)

This section provides information about limiting the page data that is returned when using the REST API.

Overview

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.

Pagination lets you:

Retrieve a limited collection of results from the server.
Offset a collection of results from the server.

Tip: To paginate, use the keywords limit and offset.On large collections, performance degrades when retrieving the later pages. Other ways to avoid stress on the database server, is to restrict the size of data returned by the query by retrieving only the data you need:

Filter the instances to be returned by using a query clause. See Query.
Retrieve only the fields you need by using a fields clause. See Select fields (fields).

Limit: Specifying the page size in the query

You can indicate the number of instances to return in each page using the query parameter.

limit has the following syntax: limit=<limit_value>

limit_value is an integer and must be greater than 0.

Example: defects?limit=20

Caution: If the limit query parameter is less than 1 or greater than the maximum page size, an exception is thrown.

This limits the number of results in a resource collection returned from the server to a specific number of results.
The total_count property in the response states the actual number of entities that answer the filter (including the ones that are brought by the specific page).
If no limit parameter is provided, the default limit is used.

Offset: 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.

offset has the following syntax: offset=<offset_value>

where offset_value is an integer and must be greater than or equal to 0.

This offsets the starting point of the collection returned from the server in the results.
If no offset parameter is provided, the number 0 is used.

Example: We have 100 defects in the system. To get 10 defects in places 40 – 49, send the following:

/defects?limit=10&offset=40

For details about the offset parameter when retrieving history using the history_records entity, see Get failed runs by checking the run history.