> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# About Pagination

> Flashduty Open API pagination mechanism

In general, when we pull or retrieve certain data objects, data is returned 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 queries as traditional pagination. In most Flashduty list query APIs, you can see the following parameter definitions:

### Request Parameters

| Parameter | Type   | Description                                                              |
| --------- | ------ | ------------------------------------------------------------------------ |
| `p`       | number | Page number, starting from 1 by default. offset = (p - 1) \* limit       |
| `limit`   | number | Number of items per page, maximum value not exceeding 100, default is 20 |

### Response Parameters

| Parameter       | Type    | Description                                              |
| --------------- | ------- | -------------------------------------------------------- |
| `total`         | number  | Total number of matched entries under current conditions |
| `has_next_page` | boolean | Whether there is next page data under current conditions |

### Example

<Tabs>
  <Tab title="Request Example">
    ```json theme={null}
    {
      "p": 1,
      "limit": 20
    }
    ```
  </Tab>

  <Tab title="Response Example">
    ```json theme={null}
    {
      "total": 1000,
      "has_next_page": true
    }
    ```
  </Tab>
</Tabs>

### Potential Issues

Although querying based on traditional pagination technology is simple, you may encounter the following issues:

<AccordionGroup>
  <Accordion title="Performance Issues">
    When using OFFSET and LIMIT for paginated 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 the previous rows, which causes queries to become slower and slower.
  </Accordion>

  <Accordion title="Data Instability">
    When using PAGE and LIMIT for paginated queries, if data is deleted or inserted during the query, results may become unstable. For example, if previous rows are deleted during the query process, subsequent offsets may become invalid, leading to inaccurate or missing results.
  </Accordion>
</AccordionGroup>

### Query Limits

To protect the system and ensure stable access for most users, we have imposed the following restrictions on API parameters based on traditional pagination technology:

<Warning>
  PAGE × LIMIT must be ≤ 10000. If it exceeds 10000, the system will directly return a 400 error. In this case, please switch to cursor pagination or narrow your query conditions.
</Warning>

***

## Cursor Pagination

***

We define pagination technology based on SEARCH\_AFTER\_CTX as cursor pagination. Cursor pagination technology can better handle large datasets and high-performance requirements, providing a more stable and efficient paginated query experience.

### Supported APIs

We provide cursor pagination support in the following APIs:

* [Incident List](/en/api-reference/on-call/incidents/incident-list)
* [Alert List](/en/api-reference/on-call/alerts/alert-read-list)

### Request Parameters

| Parameter          | Type   | Description                                                              |
| ------------------ | ------ | ------------------------------------------------------------------------ |
| `search_after_ctx` | string | Cursor index, starts from the first page when not set                    |
| `limit`            | number | Number of items per page, maximum value not exceeding 100, default is 20 |

### Response Parameters

| Parameter          | Type    | Description                                                   |
| ------------------ | ------- | ------------------------------------------------------------- |
| `total`            | number  | Total number of matched entries under current conditions      |
| `has_next_page`    | boolean | Whether there is next page data under current conditions      |
| `search_after_ctx` | string  | Next page cursor address, returned only when next page exists |

### Example

<Tabs>
  <Tab title="Request Example">
    ```json theme={null}
    {
      "search_after_ctx": "658bcbae6ab5a67b3b800230",
      "limit": 20
    }
    ```
  </Tab>

  <Tab title="Response Example">
    ```json theme={null}
    {
      "total": 1000,
      "has_next_page": true,
      "search_after_ctx": "658ba7f9566077d6090e8d51"
    }
    ```
  </Tab>
</Tabs>

***

## About TOTAL

***

Regardless of which pagination technology is used, Flashduty will return `total` and `has_next_page` parameters. However, please note that the `total` value is not always accurate. To ensure the system can respond quickly, we have added the following restrictions:

<Warning>
  * When the total matching data is less than 1000, the `total` value is exact
  * When the total matching data is greater than or equal to 1000, the `total` value is always 1000, which only indicates that the system matched 1000+ data
</Warning>

<Tip>
  Please use `has_next_page` to determine whether there is next page data, rather than `total`.
</Tip>