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

# Периоды и границы дат

> Как запросить месяц, день, последние семь дней или собственный диапазон и правильно обработать календарные границы.

Kalenich Stats считает статистику по календарю Москвы — `Europe/Moscow`. Выберите период через `period`, а сервер — через независимый параметр `server`. Если `server` не указан, API вернёт все доступные серверы за тот же период.

## Четыре режима

| Режим | Параметры дат | Значение по умолчанию | Что возвращает |
| - | - | - | - |
| `month` | Необязательный `month=YYYY-MM` | Текущий месяц по Москве | Календарный месяц |
| `day` | Необязательный `date=YYYY-MM-DD` | Сегодня по Москве | Один календарный день |
| `week` | Необязательный `date=YYYY-MM-DD` | Последние семь дней, включая сегодня по Москве | Семь календарных дней, последний из которых — `date` |
| `range` | Обязательные `from=YYYY-MM-DD` и `to=YYYY-MM-DD` | Нет | Собственный диапазон до 31 дня включительно |

<Note>
  Если `period` не передан, используется `month`. Поэтому запрос с одним `month=2026-10` остаётся корректным месячным запросом.
</Note>

## Месяц

```bash theme={null}
curl 'https://stats.kalenich.sbs/api/discord-statistics?server=02&period=month&month=2026-10'
```

Октябрь 2026 года начинается **1 октября в 00:00 по Москве включительно** и заканчивается **1 ноября в 00:00 по Москве исключительно**. Для текущего месяца счётчик отражает сохранённый отчёт на момент его формирования; итог месяца продолжает меняться.

Параметр `month` принимает значения от `2015-01` до `2099-12` в формате `YYYY-MM`.

<Warning>
  Допустимая дата означает, что запрос можно разобрать. Она не гарантирует наличие собранного отчёта за этот месяц.
</Warning>

В месячном ответе выбранный период передаётся в поле `month`:

```json Метаданные месячного ответа theme={null}
{
  "month": "2026-10",
  "timezone": "Europe/Moscow",
  "refreshMinutes": 60
}
```

Это фрагмент ответа. Значение `refreshMinutes` приведено как пример; используйте значение из полученного JSON.

## День

```bash theme={null}
curl 'https://stats.kalenich.sbs/api/discord-statistics?server=02&period=day&date=2026-10-17'
```

Запрос выбирает весь день 17 октября по Москве: от `2026-10-17 00:00` включительно до `2026-10-18 00:00` исключительно. Без `date` API выберет сегодняшний день по Москве.

## Последние семь дней

```bash theme={null}
curl 'https://stats.kalenich.sbs/api/discord-statistics?server=02&period=week&date=2026-10-17'
```

В этом запросе `date` — **последний день периода включительно**. Ответ охватывает 11–17 октября 2026 года. Без `date` период заканчивается сегодня по Москве.

<Tip>
  `week` удобно использовать для семидневного среза на выбранную дату. Это не календарная неделя с понедельника по воскресенье.
</Tip>

## Собственный диапазон

```bash theme={null}
curl 'https://stats.kalenich.sbs/api/discord-statistics?server=02&period=range&from=2026-10-09&to=2026-10-15'
```

Обе даты входят в период. Запрос выше охватывает семь календарных дней — с 9 по 15 октября. Одинаковые `from` и `to` задают один день.

Для `range` действуют три условия:

* Указаны обе даты в формате `YYYY-MM-DD`, и каждая существует в календаре.
* `from` не позже `to`.
* Между датами не более 31 календарного дня **с учётом обеих границ**. Например, 1–31 октября — 31 день, а 1 октября – 1 ноября — 32 дня.

Нарушение этих условий возвращает HTTP `400` с `error: "invalid_range"`.

## Совместимость параметров

| Выбранный `period` | Можно передавать | Нельзя передавать |
| - | - | - |
| `month` или не указан | `month`, `server` | `date`, `from`, `to` |
| `day` | `date`, `server` | `month`, `from`, `to` |
| `week` | `date`, `server` | `month`, `from`, `to` |
| `range` | `from`, `to`, `server` | `month`, `date` |

Несовместимые параметры возвращают HTTP `400` с `error: "invalid_parameters"`. Например, не добавляйте `month` к дневному запросу: календарная дата уже полностью задаёт день.

## Даты в ответе

Для `day`, `week` и `range` вместо поля `month` возвращаются следующие поля:

| Поле | Формат | Значение |
| - | - | - |
| `period` | Строка | Выбранный режим: `day`, `week` или `range` |
| `from` | `YYYY-MM-DD` | Первый календарный день, включительно |
| `to` | `YYYY-MM-DD` | Последний календарный день, включительно |
| `start` | ISO 8601 | Первый момент периода, включительно |
| `endExclusive` | ISO 8601 | Первый момент после периода, исключительно |

Ниже — фрагмент ответа на недельный запрос с `date=2026-10-17`:

```json Метаданные семидневного периода theme={null}
{
  "period": "week",
  "from": "2026-10-11",
  "to": "2026-10-17",
  "start": "2026-10-10T21:00:00.000Z",
  "endExclusive": "2026-10-17T21:00:00.000Z",
  "timezone": "Europe/Moscow",
  "refreshMinutes": 60
}
```

Суффикс `Z` обозначает UTC. В этом примере московская полночь соответствует `21:00` предыдущего дня в UTC. При фильтрации временных отметок используйте условие `timestamp >= start && timestamp < endExclusive`: оно сохраняет точные границы и не захватывает начало следующего дня.

## Архив и доступность данных

Месячные и дневные отчёты хранятся отдельно. Дневная статистика, неделя и собственный диапазон собираются из **дневных отчётов**; месячной суммы недостаточно, чтобы восстановить отдельные дни.

| Какие отчёты | Как обновляются |
| - | - |
| Текущий и предыдущий месяцы | Обновляются сборщиком |
| Сегодня и вчера | Обновляются сборщиком |
| Последние семь дней | Дневные отчёты заполняются при первоначальном сборе |
| Завершённые более старые дни | Сохраняются как снимки; доступны, если были собраны ранее |

<Warning>
  Если для сервера отсутствует хотя бы один дневной отчёт внутри запрошенного периода, его `totalMessages` будет `null`. API не подменяет полный результат суммой только доступных дней.
</Warning>

Если все дневные отчёты есть, но хотя бы один устарел, сумма сохраняется со статусом `stale`. Для составного периода `generatedAt` содержит самое раннее время формирования входящих отчётов. Состояние данных описано на странице [«Данные и статусы»](/kalenich-stats/data-and-statuses).

Запрос API читает сохранённые отчёты и **не запускает сбор**. Поле `refreshMinutes` задаёт паузу между проходами сборщика, а сам проход также занимает время. Поэтому его значение не является гарантией, что все серверы обновляются одновременно или строго раз в указанное число минут.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.