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

# ページング

> IT Management API の一覧取得エンドポイントはカーソルベースのページングをサポートしています。`cursor` パラメータと `limit` パラメータで取得範囲を制御します。

## ページング方式

IT Management API の主なページング方式は**カーソルベース**です。一部のエンドポイント（users）ではページ番号ベースを使用します。

## カーソルベースページング（主要方式）

ほとんどの一覧取得エンドポイント（people / services / devices / identity / event-logs / contracts / alerts など）はカーソルベースです。

### リクエストパラメータ

| パラメータ    | 型      | デフォルト | 最大値 | 説明                                 |
| -------- | ------ | ----- | --- | ---------------------------------- |
| `cursor` | string | —     | —   | 前回レスポンスの `nextCursor` 値。省略時は先頭から取得 |
| `limit`  | number | —     | 200 | 1回に返す件数                            |

<Info>
  `event-logs` エンドポイントでは、リクエストパラメータ名が `cursor` ではなく `nextCursor` になります。
</Info>

### レスポンス形式

```json theme={null}
{
  "meta": {
    "nextCursor": "F3UdkoSbpBNrjwP93AX2HQ",
    "totalItems": 100
  },
  "items": [
    // リソースの配列
  ]
}
```

### レスポンスフィールド

| フィールド             | 型               | 説明                          |
| ----------------- | --------------- | --------------------------- |
| `meta.nextCursor` | string \| null  | 次ページ取得用カーソル。`null` のとき最終ページ |
| `meta.totalItems` | integer \| null | 総件数。`null` になることがある         |
| `items`           | array           | 取得したリソースの配列                 |

### 使用例

```bash theme={null}
# 最初のページを取得
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.itmc.i.moneyforward.com/api/v1/organizations/YOUR_ORG_ID/people?limit=50"

# 次のページを取得（前回レスポンスの nextCursor を使用）
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.itmc.i.moneyforward.com/api/v1/organizations/YOUR_ORG_ID/people?cursor=F3UdkoSbpBNrjwP93AX2HQ&limit=50"
```

```javascript theme={null}
async function fetchAllPeople(orgId) {
  const allItems = [];
  let cursor = undefined;

  do {
    const params = new URLSearchParams({ limit: '200' });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(
      `https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}/people?${params}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );

    const data = await response.json();
    allItems.push(...data.items);
    cursor = data.meta.nextCursor;
  } while (cursor);

  return allItems;
}
```

## ページ番号ベースページング（users エンドポイント）

`GET /api/v1/organizations/{id}/users` はページ番号ベースのページングを使用します。

### リクエストパラメータ

| パラメータ   | 型      | 説明           |
| ------- | ------ | ------------ |
| `page`  | number | ページ番号（1 始まり） |
| `limit` | number | 1ページあたりの件数   |

### レスポンス形式

```json theme={null}
{
  "metadata": {
    "prevPage": 1,
    "nextPage": 3
  },
  "users": [
    // ユーザーの配列
  ]
}
```

## ベストプラクティス

1. `nextCursor` が `null` になるまでループして全件取得する
2. 必要以上に大きな `limit` を指定しない（上限: 200）
3. `totalItems` は `null` になることがあるためループ終了の判定には使用せず、`nextCursor` の有無で判断する