# Статистика

Сводка расхода и генераций для личного кабинета

Базовый адрес — `https://api.iskragen.ru`. Общие правила — в [обзоре справочника](/docs/api-reference).

## GET /v1/stats/dashboard

**Сводка за 7 дней.** Возвращает расход и генерации за последние 7 календарных дней по Москве со сравнением с предыдущими 7 днями; период фиксирован, параметров нет. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Пример вызова

```bash
curl -X GET "https://api.iskragen.ru/v1/stats/dashboard" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY"
```

### Структура ответа `200`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `activity` | `object[]` | да | — |
| `activity[].count` | `integer` | да | ≥ 1 |
| `activity[].dow` | `integer` | да | ≥ 0; ≤ 6 |
| `activity[].hour` | `integer` | да | ≥ 0; ≤ 23 |
| `balanceSeries` | `object[]` | да | элементов ≤ 30 |
| `balanceSeries[].at` | `string` | да | формат date-time |
| `balanceSeries[].balanceAfterRub` | `string` | да | шаблон `^-?(?:0\|[1-9][0-9]{0,15})(?:\.[0-9]{1,2})?$` |
| `generations` | `object` | да | — |
| `generations.avgDurationMs` | `integer \| null` | да | — |
| `generations.byDay` | `object[]` | да | элементов ≥ 7; элементов ≤ 7 |
| `generations.byDay[].count` | `integer` | да | ≥ 0 |
| `generations.byDay[].date` | `string` | да | формат date |
| `generations.total` | `integer` | да | ≥ 0 |
| `period` | `object` | да | — |
| `period.days` | `number` | да | значения: `7` |
| `period.from` | `string` | да | формат date-time |
| `period.to` | `string` | да | формат date-time |
| `spend` | `object` | да | — |
| `spend.byDay` | `object[]` | да | элементов ≥ 7; элементов ≤ 7 |
| `spend.byDay[].amountRub` | `string` | да | шаблон `^-?(?:0\|[1-9][0-9]{0,15})(?:\.[0-9]{1,2})?$` |
| `spend.byDay[].date` | `string` | да | формат date |
| `spend.deltaPct` | `number \| null` | да | — |
| `spend.prevWeekRub` | `string` | да | шаблон `^-?(?:0\|[1-9][0-9]{0,15})(?:\.[0-9]{1,2})?$` |
| `spend.weekRub` | `string` | да | шаблон `^-?(?:0\|[1-9][0-9]{0,15})(?:\.[0-9]{1,2})?$` |
| `topModels` | `object[]` | да | элементов ≤ 5 |
| `topModels[].count` | `integer` | да | ≥ 0 |
| `topModels[].modelId` | `string` | да | Устарело: внутренний идентификатор. Используйте modelSlug.; длина ≥ 1 |
| `topModels[].modelSlug` | `string` | нет | Всегда присутствует в ответе; публичный идентификатор модели; длина ≥ 1 |
| `topModels[].name` | `string` | да | длина ≥ 1 |
| `topModels[].spendRub` | `string` | да | шаблон `^-?(?:0\|[1-9][0-9]{0,15})(?:\.[0-9]{1,2})?$` |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).