Pagination and Filtering

List methods return one page at a time. Use request builders to control page size, sorting and filters.

Every list-operation page contains its own filter constants, value types, examples and response model. This page documents only the behavior shared by all lists.

Defaults

Field	Default	Description
page	0	Zero-based page index
size	20	Items requested per page
sortBy	ID	Sort field
direction	DESC	Sort direction

Examples

const filterRequest: DeviceFilterRequest = {
  key: DeviceFilter.PLATFORM,
  value: "android",
  operation: SearchOperation.EQUAL
};

const request = new ListDevicesRequestBuilder()
  .page(0)
  .size(50)
  .sortBy("ID")
  .direction(SortDirection.DESC)
  .filters([filterRequest])
  .build();

const devices = await client.devices().list(request);

The Java and Node.js SDKs transmit filters for device, pool, application, allocation, session and screen-record list requests. See the individual operation page for the exact constants and accepted values. listByDefaultPool(...) is a convenience method that applies the default-pool filter automatically.

Java examples use Collections.singletonList(filterRequest) because the SDK targets Java 8. On Java 9 or newer, List.of(filterRequest) is equivalent.

How SDK Filters Are Sent

const filterRequest: DeviceFilterRequest = {
  key: DeviceFilter.POOL_ID,
  value: "pool-123",
  operation: SearchOperation.EQUAL
};

const request = new ListDevicesRequestBuilder()
  .filters([filterRequest])
  .page(0)
  .size(10)
  .build();

The SDK maps that rule to indexed query values:

filters[0].key=devicePools.id
filters[0].value=pool-123
filters[0].operation=EQUAL
sorting.page=0
sorting.size=10
sorting.sortBy=ID
sorting.direction=DESC

Rules passed to .filters(...) keep their list order and are indexed as filters[0], filters[1] and so on.

Search Operations

Operation	Use
EQUAL	Match the exact value
NOT_EQUAL	Exclude the exact value
GREATER_THAN	Match values greater than the supplied value
LESS_THAN	Match values less than the supplied value

Operation-Specific Filters

List operation	Filter details and response
Devices	Pool, serial, name, manufacturer, model, platform, OS, tag and state
Device apps (Node.js only)	Bundle identifier, default status and file key
Pools	Pool name and default-pool status
Allocations	Allocation id
Sessions	Allocation, session, serial and state
Screen records	Created timestamp
Applications	File key, file path, version and revision

Page Result

Every list method returns PageDto<T> with page, size, totalPages, totalElements and data.

To read every item, increase the page index until the last page. Avoid requesting an unbounded page size.

Read Every Node.js Page

let page = 0;

while (true) {
  const result = await client.devices().list(
    new ListDevicesRequestBuilder().page(page).size(100).build()
  );

  for (const device of result.data) {
    console.log(device.serial);
  }

  if (page >= result.totalPages - 1) {
    break;
  }

  page += 1;
}

Use a bounded page size to avoid large responses and request timeouts.

Questions This Contract Answers

Do I need to fetch every device and filter locally?

Use supported filters directly in Java or Node.js. Device, pool, application, allocation, session and screen-record filters are sent server-side.

Does List Pools include pool devices?

No. It returns PageDto<Pool> with pool id and name. Use List Devices with POOL_ID where supported.

What does an empty data array mean?

The request succeeded but no visible record matched the page and filter criteria.