# Pagination

Pagination makes sure that only a part (called **page**) of the resources is being returned during **GET** retrieval (listing). This is especially useful when a large amount of resources has been created. \
For example you may have created tens of thousands of rooms and it would be impractical to retrieve all of them in one GET request/response. That would put a huge strain on the bandwidth.

To paginate you need to use a combination of the following three parameters:

* **limit ->** limits the number of returned records in the page. Maximum and default value is **100**.
* **order ->** determines the sorting order of the result. Ascending (**asc**) or descending (**desc**). Default value is "**desc**" = descending and the order is by the `creation time` of the records.
* **after ->** used as a cursor to browse through all pages. That is the **id** of the last record from the previous page. For examples read immediately below.
* **offset** -> useful for table pagination where you want to retrieve records of a concrete page. The **after** param is on the contrary useful for infinite scroll type of pagination.

```
-- This returns maximum of 30 rooms sorted by descending order of creation time.
https://api.digitalsamba.com/api/v1/rooms?limit=30

-- This returns maximum of 30 rooms, sorted by ascending order of creation time
https://api.digitalsamba.com/api/v1/rooms?limit=30&order=asc

-- This returns maximum of 20 rooms, sorted by descending order of creation time.
-- Also includes the "after" cursor with a room id. 
-- Note that the provided value for "after" is just a random example.
https://api.digitalsamba.com/api/v1/rooms?limit=20&order=desc&after=48559760-8553-33d5-b016-a9efb48d37c7

-- This returns maximum of 20 rooms, sorted by descending order of creation time.
-- Also includes the "offset" param which skips 40 records, 
-- which means the 3rd page will be returned (20 * 2).
https://api.digitalsamba.com/api/v1/rooms?limit=20&offset=40&order=desc
```

#### Pseudocode example how to paginate through all of your rooms 

It loops using the **after** param as cursor until no more rooms are available.

```java
String BASE_ROOMS_URL = "https://api.digitalsamba.com/api/v1/rooms";

//This retrieves the 1st page (default limit is 100 items)
List<Room> room = getRooms(BASE_ROOMS_URL);

while (!rooms.isEmpty()) {
   //Process the current page according to your needs
   process(rooms);
   
   //Now retrieve the next page (default limit is again 100 items)
   Room lastRoomInPage = rooms.get(rooms.size() - 1);
   rooms = getRooms(BASE_ROOMS_URL + "?after=" + lastRoomInPage.getId());
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalsamba.com/reference/rest-api/pagination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.