Pagination

For endpoints that can return long lists of resources, using pagination makes your app faster and more efficient. The Seam API and our JavaScript, Python, PHP, and Ruby SDKs support pagination for list endpoints.

Currently, we support pagination for access codes, access system users, Connect Webviews, connected accounts, and devices.

To fetch and process resources across multiple pages in the Seam API, use the limit and page_cursor parameters, along with the pagination response object. The pagination object provides the following information:

Property	Type	Description
next_page_cursor	String	Opaque value that you use to select the next page of results through the page_cursor parameter.
has_next_page	Boolean	Indicates whether there is another page of results after this one.
next_page_url	String (URI)	URL to get the next page of results.

For pagination in the Seam SDKs, use the corresponding paginator class, for example, SeamPaginator in the Seam JavaScript and Python SDKs and Paginator in the Seam PHP and Ruby SDKs.

The following examples show you how to use pagination in a variety of scenarios:

Manually Fetch Pages

You can specify the number of records per page and the desired page of results. The first list request returns the first set of records, as well as the pagination object. If pagination.has_next_page is true, you can request an additional page of records. For all list requests after the first, use the pagination.next_page_cursor as the value for the page_cursor parameter.

The following example gets the first page of 20 devices and then the second page of 20 devices:

Python

Code:

paginator = seam.create_paginator(seam.devices.list, {"limit": 20})

devices, pagination = paginator.first_page()

if pagination.has_next_page:
    more_devices, _ = paginator.next_page(pagination.next_page_cursor)

Output:

[
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    ...
  ),
  ...
]

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Resume Pagination

You can get the first page on initial load, store the state, and then get the next page at a later time using the stored state.

The following example gets the first page of 20 records from the list of devices and, later, gets the next page of 20 devices:

Python

Code:

# Get the first page.
params = {"limit": 20}
paginator = seam.create_paginator(seam.devices.list, params)

devices, pagination = paginator.first_page()

# Store the state, for example, in memory, a file, or a database.
pagination_state = {
    "params": params,
    "next_page_cursor": pagination.next_page_cursor,
    "has_next_page": pagination.has_next_page,
}
with open("/tmp/seam_devices_list.json", "w") as f:
    json.dump(pagination_state, f)
    
# Get the next page at a later time using the stored state.
with open("/tmp/seam_devices_list.json", "r") as f:
    pagination_state = json.load(f)

if pagination_state.get("has_next_page"):
    paginator = seam.create_paginator(
        seam.devices.list, pagination_state["params"]
    )
    more_devices, _ = paginator.next_page(
        pagination_state["next_page_cursor"]
    )

Output:

[
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    ...
  ),
  ...
]

[
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    ...
  ),
  ...
]

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Iterate Over All Pages

You can iterate over all pages of records.

The following example uses a loop to get all pages of records for a list of 65 devices, at 20 records per page:

Python

Code:

pages = seam.create_paginator(
  seam.devices.list(
    limit=20
  )
)

for devices in pages:
  pprint(f"There are {len(devices)} devices on this page.")

Output:

There are 20 devices on this page.
There are 20 devices on this page.
There are 20 devices on this page.
There are 5 devices on this page.

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Iterate Over All Resources

You can iterate over all resources within all pages.

The following example uses a loop to get all records for a list of devices, at 20 records per page, and then prints out the device ID for each record:

Python

Code:

paginator = seam.create_paginator(seam.devices.list, {"limit": 20})

for device in paginator.flatten():
    print(device.device_id)

Output:

'11111111-1111-1111-1111-444444444444'
'11111111-1111-1111-2222-444444444444'
...

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Return All Resources Across All Pages as an Array

You can iterate over all resources within all pages and return a single array or list.

The following example returns an array containing all devices:

Python

Code:

paginator = seam.create_paginator(seam.devices.list, {"limit": 20})

all_devices = paginator.flatten_to_list()

Output:

[
  Device(
    device_id='11111111-1111-1111-1111-444444444444',
    ...
  ),
  Device(
    device_id='11111111-1111-1111-2222-444444444444',
    ...
  ),
  ...
]

cURL (bash)

JavaScript

Ruby

PHP

C#