REST API methods that might return a large number of individual elements support pagination. Some examples of these methods includeQuery Datasources andGet Users in Site. When you call these methods, the response includes a<pagination> element that haspageNumber,pageSize, andtotalAvailable attributes whose values you can use to implement paging.

The following example shows what the response body might look like for aGet Users in Site request where there are a total of 158 users in the site:

<?xml version="1.0"?><tsResponse><pagination pageNumber="1" pageSize="100" totalAvailable="158"/>  <users>    <user name="Ashley"          siteRole="None" lastLogin="" externalAuthUserId=""/>    <user name="Michelle"           siteRole="PublisherInteractor"  lastlogin=" " externalAuthUserId=""/>    <user name="Alan"          siteRole="Publisher" lastLogin="" externalAuthUserId=""/>    <user name="Susan"          siteRole="Viewer" lastLogin="" externalAuthUserId=""/>    <user name="Laura"          siteRole="Interactor" lastLogin="" externalAuthUserId=""/>    <user name="Andrew"          siteRole="PublisherInteractor" lastLogin="" externalAuthUserId=""/>    <user name="Adam"          siteRole="Interactor" lastLogin="" externalAuthUserId=""/>    <user name="Henry"          siteRole="PublisherInteractor" lastLogin="" externalAuthUserId=""/>    <user name="Fred"          siteRole="Viewer" lastLogin="" externalAuthUserId=""/>    <user name="Jane"           siteRole="PublisherInteractor" lastLogin="" externalAuthUserId=""/>    ... Another 90 <user> elements here ...  </users></tsResponse>

If a method supports pagination, you can pass two parameters as part of the request: the page size (that is, the number of elements to return per call) and the page number. The default page size for an individual call is 100, but you can specify a page size that’s any positive integer. The page number is a 1-based (not zero-based) value. The default page number is 1, meaning that if you do not include a page number, Tableau Server returns the first page of elements.

You pass page number and page size parameters using the query string on the URI, as in this example:

http://myserver/api/3.27/sites/site-id/users?pageSize=20&pageNumber=2

The page number is multiplied by the current page size to determine which elements to return. For example, if the page size is 20 and the page number is 2, the call returns items 21 through 40 of all available elements.

To use pagination, you typically perform a series of requests in a loop. Each iteration of the loop gets another page of elements until you have received all available elements.

How Elements are Ordered

To maintain consistency, if no explicit sort order is specified (seeFiltering and Sorting in the Tableau REST API) the elements returned are indexed and sorted internally. For example, if a method returns 158 elements, those items will be sorted and listed in the same order in subsequent method calls. The sorting is done on an internal index, and not on the locally unique identifier (LUID) for the resource (for example, not on the userid).

Note that the REST methods are not synchronized, so if another method removes an item from the list, between paging calls, it is possible that some items might be missed if they fall on a page boundary. The effect is temporary, as no data is lost, and further requests sort and index the elements correctly.

Python Example for Paging

The following example in Python shows how to use paging to get a list of users on the site. Note the following about this example:

• The example is not complete. It assumes that you previously called theSign In method and got back an authentication token that you've stored the token in the variable namedtoken. It also assumes that you got back the site ID and have stored it in the variable namedsite_id. For more information, seeSigning In and Signing Out (Authentication).

• The code makes HTTP requests using theRequest library that's built into Python.

• The code parses the XML block in the response body using thexml.etree.ElementTree method that's built into Python. For details, see theElementTree XML API(Link opens in a new window) documentation on the Python website.

try:    # Python 3    from urllib.request import urlopen, requestexcept:    # Python 2    from urllib2 import urlopen, Requestimport xml.etree.ElementTree as ET # For parsing XML responses# ... Code here to sign in ...# Note: A Sign In request has already been made and the authentication token is# in the variable named "token"headers = {'X-tableau-auth': token}page_size = 50page_number = 1  # 1-based, not zero basedtotal_returned = 0done = Falseuser_name_list = []while not(done):    request_url = 'http://{server}/api/3.27/sites/{site_id}/users'.format(        server=server, site_id=site_id)    paging_parameters = '?pageSize={page_size}&pageNumber={page_number}'.format(        page_size=page_size, page_number=page_number)    full_url = request_url + paging_parameters    print(full_url)    # Make request    req = Request(full_url, headers=headers)    req = urlopen(req)    server_response = req.read().decode("utf8")    response_xml = ET.fromstring(server_response)    # Get total number of records from the <pagination> element    total_available = response_xml.find('.//t:pagination',        namespaces={'t': "http://tableau.com/api"}).attrib['totalAvailable']    # Note! Need to convert "total_available" to integer    total_available = int(total_available)    page_number += 1    total_returned += page_size    # Get user details from <users> element    user_element = response_xml.findall('.//t:user',        namespaces={'t': "http://tableau.com/api"})    # Display individual user names    for user in user_element:        print (user.attrib['name'])    if(total_returned >= total_available):        done = True# ... Code here to sign out ...