About Pagination

---

title: "About Pagination"
description: "Introduction to Flashduty Open API Pagination."
date: "2024-11-20T10:00:00+08:00"
url: "https://developer-en.flashcat.cloud/en/flashduty/open-api/about-pagination"

---

Generally, when fetching or retrieving data objects, we return data in batches based on pagination rather than returning all data in a single request.

Traditional Pagination

We define pagination technology based on OFFSET and LIMIT as traditional pagination. In most Flashduty list query APIs, you'll see the following parameter definitions:

{
    "p": 1,     // Page number, starts from 1. offset=(p-1)*limit
    "limit": 20 // Items per page, maximum value is 100, default is 20
}

In the response, we return these parameters:

{
    "total": 1000,       // Total number of items matching current conditions
    "has_next_page": 20  // Whether there is a next page under current conditions
}

While traditional pagination is simple, it may encounter these issues:

1. Performance issues: When using OFFSET and LIMIT for pagination queries, the database needs to skip a specified number of rows (OFFSET) and then return a specified number of rows (LIMIT). As the offset increases, query performance may decrease, especially when handling large amounts of data. Each query needs to scan and skip previous rows, making queries progressively slower.

2. Data instability: When using PAGE and LIMIT for pagination queries, if data is deleted or inserted during the query, results may become unstable. For example, if rows are deleted during the query process, subsequent offsets may become invalid, leading to inaccurate or missing results.

To protect the system and ensure stable access for most users, we've implemented these limitations for APIs using traditional pagination:

:::caution
PAGE * LIMIT must be <= 10000. If it exceeds 10000, the system will return a 400 error. In this case, please switch to cursor pagination or narrow your query conditions.
:::

Cursor Pagination

We define pagination technology based on SEARCH_AFTER_CTX as cursor pagination. Cursor pagination can better handle large datasets and high-performance requirements, providing a more stable and efficient pagination experience.

We support cursor pagination in these APIs:
Incident List
Alert List

In these APIs, you'll see these parameter definitions:

{
    "search_after_ctx": "658bcbae6ab5a67b3b800230",  // Cursor index, starts from first page if not set
    "limit": 20 // Items per page, maximum value is 100, default is 20
}

In the response, we return these parameters:

{
    "total": 1000,       // Total number of items matching current conditions
    "has_next_page": 20, // Whether there is a next page under current conditions
    "search_after_ctx": "658ba7f9566077d6090e8d51" // Next page cursor address, returned only if next page exists
}

About TOTAL

Regardless of pagination technology used, Flashduty always returns TOTAL and HAS_NEXT_PAGE parameters. However, note that TOTAL value isn't always accurate. To ensure quick system response, we've added these limitations:

:::caution
When total matching data is less than 1000, total value is exact;
When total matching data is greater than or equal to 1000, total value is always 1000. This only indicates the system matched 1000+ items.
:::

Therefore, please use has_next_page to determine if there's a next page, rather than total.