Пагинация и форматы данных

Пагинация

Эндпоинты, которые могут вернуть много записей, отдают данные постранично. Номер страницы передаётся в параметре page (нумерация с 1), а размер страницы — в page_size или per_page, в зависимости от эндпоинта. Максимальный размер страницы — 100.

Ответ содержит массив записей и объект pagination. Если запросить страницу за пределами выдачи, вернётся пустой массив.

Параметры `page` и `page_size`

GET /v1/checks?page=2&page_size=50

{
  "checks": [ ... ],
  "pagination": {
    "page": 2,
    "page_size": 50,
    "total_pages": 4,
    "total_items": 183
  }
}

Поле	Описание
`page`	Номер текущей страницы.
`page_size`	Размер страницы.
`total_pages`	Общее количество страниц.
`total_items`	Общее количество записей.
`has_next`, `has_prev`	Есть ли следующая и предыдущая страница. Возвращаются не всеми эндпоинтами.

Эндпоинт	Ключ массива	`page_size` по умолчанию
`GET /v1/checks`	`checks`	20
`GET /v1/checks/{check_id}/results`	`results`	20
`GET /v1/checks/{check_id}/status-history`	`status_history`	20
`GET /v1/checks/all-results`	`results`	20
`GET /v1/checks/{check_id}/execution-groups`	`execution_groups`	20
`GET /v1/check-groups`	`groups`	20
`GET /v1/check-groups/{group_id}/checks`	`checks`	20
`GET /v1/secrets`	`secrets`	20
`GET /v1/pages`	`pages`	20
`GET /v1/reports`	`reports`	20

GET /v1/reports возвращает в pagination только поля page, page_size и total.

Параметры `page` и `per_page`

GET /v1/heartbeats?page=1&per_page=20

{
  "checks": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "pages": 3,
    "total": 45
  }
}

Поле	Описание
`page`	Номер текущей страницы.
`per_page`	Размер страницы.
`pages`	Общее количество страниц.
`total`	Общее количество записей.
`has_next`, `has_prev`	Есть ли следующая и предыдущая страница. Возвращаются не всеми эндпоинтами.

Эндпоинт	Ключ массива	`per_page` по умолчанию
`GET /v1/heartbeats`	`checks`	50
`GET /v1/heartbeats/{check_id}/pings`	`pings`	50
`GET /v1/checks/jobs`	`jobs`	20
`GET /v1/alerts`	`alerts`	20
`GET /v1/pages/{page_id}/subscribers/notifications`	`notifications`	25
`GET /v1/audit`	`audit_logs`	50

Списки без пагинации

Эти эндпоинты возвращают все записи сразу:

компоненты и группы компонентов Статус Страницы;
инциденты, включая /incidents/unresolved и /incidents/maintenance;
подписчики Статус Страницы;
пользователи организации и API ключи;
справочники: /v1/component-statuses, /v1/incident-statuses, /v1/incident-impacts, /v1/maintenance-statuses, /v1/checks/check-templates.

Пример: получить все проверки

import requests

API_KEY = "ВАШ_API_КЛЮЧ"
url = "https://api.pingera.ru/v1/checks"

checks = []
page = 1
while True:
    response = requests.get(
        url,
        headers={"Authorization": API_KEY},
        params={"page": page, "page_size": 100},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()
    checks.extend(data["checks"])
    if page >= data["pagination"]["total_pages"]:
        break
    page += 1

print(f"Всего проверок: {len(checks)}")

Фильтрация по датам

Эндпоинты с результатами проверок принимают параметры start_date и end_date в формате ISO 8601. Всегда указывайте часовой пояс, например суффикс Z для UTC: 2026-10-01T00:00:00Z.

GET /v1/checks/all-results?start_date=2026-10-01T00:00:00Z&end_date=2026-10-07T23:59:59Z

GET /v1/checks/all-results по умолчанию возвращает результаты за последние 7 дней. Данные доступны за последние 6 месяцев: если start_date раньше, API вернёт результаты начиная с этой границы.

Даты и время

Даты в ответах API передаются в формате ISO 8601 и всегда в UTC. Обычно суффикс часового пояса не указывается:

"created_at": "2026-10-08T10:15:42.123456"

Разбирая такие значения, явно указывайте часовой пояс UTC, иначе библиотека может посчитать время локальным.

from datetime import datetime, timezone

created_at = datetime.fromisoformat("2026-10-08T10:15:42.123456").replace(tzinfo=timezone.utc)

Идентификаторы

Идентификаторы ресурсов — строки из 12 символов: строчные латинские буквы и цифры, например 5rs9dvpvyyp8. Не полагайтесь на формат идентификатора в своей логике и храните его как строку.