> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/he-xin-gai-nian/pagination.md).

# 分頁

列表型端點使用 offset / limit 分頁。你可以透過 limit 控制每頁筆數，透過 offset 指定從第幾筆開始讀取。

## 查詢參數

| 參數       | 預設   | 上限     | 說明             |
| -------- | ---- | ------ | -------------- |
| `limit`  | `20` | `1000` | 每頁最多回傳筆數       |
| `offset` | `0`  | —      | 起始位移，表示略過前幾筆資料 |

```bash
curl "https://api.blockchainsecurity.asia/v1/webhooks?limit=50&offset=100" \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

{% hint style="warning" %}
limit 必須大於 0；若超過上限，系統會回傳 400 bad\_request。系統不會自動截斷超額 limit，避免客戶端誤以為已取得完整資料。
{% endhint %}

## 分頁中繼資訊

分頁資訊會出現在 response.meta.pagination 中：

```json
{
  "data": [ /* ... */ ],
  "meta": {
    "pagination": { "limit": 50, "offset": 100, "total": 1342 }
  }
}
```

| 欄位       | 說明                         |
| -------- | -------------------------- |
| `limit`  | 本次採用的每頁筆數                  |
| `offset` | 本次查詢的起始位移                  |
| `total`  | 符合條件的總筆數；部分高成本或即時資料端點可能不提供 |

## 翻頁

要取得下一頁，將 offset 加上 limit：

```
第 1 頁：offset=0,   limit=50
第 2 頁：offset=50,  limit=50
第 3 頁：offset=100, limit=50
```

當回傳筆數少於 limit，通常代表已到最後一頁。若 response.meta.pagination.total 存在，也可用 offset + limit >= total 判斷是否已無下一頁。

## 最佳實務

最佳實務

• 固定查詢條件：翻頁期間請保持相同的查詢條件、排序與 filter，避免結果重複或遺漏。

• 避免過大 limit：較大的 limit 可能增加延遲與記憶體消耗；大量資料建議分批拉取。

• 記錄 offset：批次任務建議記錄最後成功處理的 offset，失敗時可從中斷位置繼續。

• 高變動資料需注意：交易、地址活動、資金流等資料可能持續新增；若需要穩定快照，建議搭配時間區間條件，例如 start\_time / end\_time。

### 下一步

{% content-ref url="/pages/qnj2vPgmFyRFTLqtmCVj" %}
[Webhook 訂閱](/documentation/events/webhooks.md)
{% endcontent-ref %}