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

# Пагінація груп оголошень

> Offset-пагінація для ендпоінта GET /ad-groups

<Note>
  This page is also available in [English](/guides/ad-groups-pagination).
</Note>

## Огляд

`GET /ad-groups` тепер повертає **пагіновану відповідь** замість простого масиву.
Використовуйте параметри `offset` і `limit` для навігації по сторінках.

<Warning>
  **Зламуюча зміна** — формат відповіді змінився. FE код, який обробляє
  відповідь як масив, потрібно оновити для читання `.results`.
</Warning>

***

## Формат відповіді

Ендпоінт тепер повертає об'єкт з метаданими пагінації:

```json theme={null}
{
  "results": [
    {
      "id": 123456,
      "name": "My Ad Group",
      "campaign_id": 789,
      "campaign_name": "Campaign A",
      "status": "ENABLED",
      "type": "SEARCH_STANDARD",
      "metrics": { ... }
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}
```

| Поле      | Тип               | Опис                                        |
| --------- | ----------------- | ------------------------------------------- |
| `results` | `AdGroupSchema[]` | Поточна сторінка груп оголошень             |
| `total`   | `int`             | Загальна кількість після фільтрації пошуком |
| `limit`   | `int`             | Значення `limit`                            |
| `offset`  | `int`             | Значення `offset`                           |

***

## Параметри запиту

| Параметр | Тип   | За замовчуванням | Опис                             |
| -------- | ----- | ---------------- | -------------------------------- |
| `limit`  | `int` | `50`             | Максимум елементів на сторінку   |
| `offset` | `int` | `0`              | Кількість елементів для пропуску |

Ці параметри працюють разом з існуючими (`search`, `exclude_removed` тощо).

***

## Приклади використання

<Tabs>
  <Tab title="Перша сторінка (за замовчуванням)">
    ```
    GET /api/v1/google-ads/{customer_id}/ad-groups
    ```

    Повертає перші 50 груп оголошень з `total`, що відображає загальну кількість.
  </Tab>

  <Tab title="Друга сторінка">
    ```
    GET /api/v1/google-ads/{customer_id}/ad-groups?offset=50&limit=50
    ```

    Пропускає перші 50 результатів і повертає наступні 50.
  </Tab>

  <Tab title="Пошук + пагінація">
    ```
    GET /api/v1/google-ads/{customer_id}/ad-groups?search=brand&offset=0&limit=20
    ```

    `total` відображає кількість груп оголошень, що відповідають "brand",
    а не загальну кількість.
  </Tab>
</Tabs>

***

## Інтеграція на фронтенді

Оновіть виклик API для обробки нового формату відповіді:

```typescript theme={null}
// Раніше (простий масив)
const adGroups = await api.get<AdGroup[]>("/ad-groups", { params });

// Зараз (пагінований об'єкт)
const { results, total, limit, offset } = await api.get<{
  results: AdGroup[];
  total: number;
  limit: number;
  offset: number;
}>("/ad-groups", { params: { ...params, offset: page * pageSize, limit: pageSize } });

const totalPages = Math.ceil(total / limit);
```

***

## Примітки

* **CSV ендпоінт** (`GET /ad-groups/csv`) не змінився — він продовжує
  повертати плоский CSV файл.
* `total` завжди відображає кількість **після** фільтрації пошуком, але
  **до** нарізки пагінацією.