Skill: horosheff/yandex-metrika-assistant (version 1.0.0)

--- name: yandex-metrika-assistant description: OpenClaw + Яндекс.Метрика API — stat/Logs/management, OAuth, presets, UTM, цели, CSV, квоты; плагин yandex-metrika-assistant. homepage: https://github.com/Horosheff/yandex-metrika-assistant --- # Яндекс.Метрика API — заточка под **OpenClaw** Плагин: **`yandex-metrika-assistant`** (`openclaw.plugin.json` в этой папке). Цель: ноль сюрпризов — сначала **конфиг и секреты**, потом **правильный endpoint**, без выдуманных метрик и без утечки токена. --- ## Онбординг человека (порядок ответов агента) **Если токена ещё нет** (пользователь только ставит навык или не настроил ключ): 1. **Сначала** дай ссылку и краткое резюме установки: **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`** (шаги OpenClaw + OAuth + куда вставить ключ). 2. **Обязательно** перечисли, какие **галочки в приложении Яндекс OAuth** нужны для Метрики (таблица из того же файла / шаг 2): статистика и чтение, создание/изменение счётчиков, при необходимости расходы, параметры пользователей, офлайн-данные. 3. Укажи **канал поддержки:** [**https://t.me/maya_pro**](https://t.me/maya_pro) — вопросы по установке и сценариям; **не** проси кидать токен в Telegram публично. 4. Затем — получение токена: **`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`** (или ссылка `authorize` с `oauthClientId` из конфига). 5. Напомни: ключ хранить в **`oauthToken`** плагина или в **`YANDEX_METRIKA_OAUTH_TOKEN`**, не в чате. **После того как ключ добавлен** (пользователь сообщил, что сохранил токен в конфиг, или токен уже есть в конфиге/окружении): - Не проси продиктовать токен. - Заверши ответ блоком **«С чего начать»** — предложи **3–5 коротких вариантов** (нумерованный список), например: 1. Показать список счётчиков Метрики. 2. Визиты по дням за последние 7 дней. 3. Сводка по источникам трафика. 4. Топ страниц по просмотрам. 5. Конверсии по цели (если есть цели). Полный список идей — **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`** (раздел «После добавления ключа») и **`{baseDir}/docs/10-user-intents-matrix.md`**. --- **Типовые формулировки пользователей** («откуда трафик», «цели», «UTM», «география», «сравни периоды», «выгрузи CSV», «сырые логи») — смотри матрицу: **`{baseDir}/docs/10-user-intents-matrix.md`** (разбивка по разделам A–J + ссылки на официальные примеры и пресеты). --- ## OpenCLaw: порядок работы (строго) 1. **Токен** брать только из: - настроек плагина **`oauthToken`** (см. `configSchema` в `openclaw.plugin.json`), **или** - переменной окружения **`YANDEX_METRIKA_OAUTH_TOKEN`** (если хост OpenClaw так настроен), **или** - пользователь явно передал токен **один раз** для текущей сессии — тогда использовать, но **не** повторять токен обратно в ответе и **не** вставлять в файлы репозитория. 2. Если токена **нет** — **не** вызывать API и **не** придумывать ответ Метрики. Следуй разделу **«Онбординг человека»** выше: сначала **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`**, галочки OAuth, [**@maya_pro**](https://t.me/maya_pro), затем **`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`**; при наличии **`oauthClientId`** — ссылка `authorize?response_type=token&client_id=...`. 3. **`defaultCounterId`** из конфига: если пользователь не назвал счётчик — используй это значение и **одной строкой** напиши: «использую счётчик по умолчанию из конфига OpenClaw». 4. Любые `curl`/команды в чат — только с плейсхолдером **`$env:YANDEX_METRIKA_OAUTH_TOKEN`** или «подставь токен из секрета OpenClaw», **не** вставляй токен целиком. 5. **Windows / PowerShell:** если `curl -H "Authorization: OAuth …"` даёт ошибки из‑за кавычек — используй **`Invoke-RestMethod`** с `-Headers @{ Authorization = 'OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN }`** или заголовок через **конкатенацию** в скобках: `-H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)`. Подробно: **`{baseDir}/docs/OPENCLAW-AGENT.md`**, **`{baseDir}/docs/EXAMPLES.md`**. --- ## Быстрые рецепты (копипаста для пользователя, Windows PowerShell) Подстановка токена из env (удобно рядом с OpenClaw): ```powershell $env:YANDEX_METRIKA_OAUTH_TOKEN = "<секрет, не коммитить>" $cid = "<COUNTER_ID>" # Надёжнее без вложенных кавычек вокруг токена: curl.exe -s -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) ` "https://api-metrika.yandex.net/management/v1/counters?per_page=20" ``` Отчёт «визиты за последние 7 дней» (проверь `ids` и метрики по задаче): ```powershell curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" ` --data-urlencode "ids=$cid" ` --data-urlencode "metrics=ym:s:visits" ` --data-urlencode "date1=7daysAgo" ` --data-urlencode "date2=yesterday" ` -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) ``` --- ## Сценарий: «пришли ежедневную статистику по сайту maya» Так OpenClaw **должен** отработать запрос (и что увидит человек в ответе). ### Внутренние шаги агента 1. **Токен** — из `oauthToken` / `YANDEX_METRIKA_OAUTH_TOKEN`. Нет токена → стоп, ссылка на `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`. 2. **Счётчик** — если в конфиге есть **`defaultCounterId`** и пользователь не просил другой сайт, можно спросить: «использовать счётчик по умолчанию?» или сразу использовать, если контекст однозначен. 3. Иначе: **`GET /management/v1/counters`** с **`search_string=maya`** (или фрагмент домена: `mayai`, `blog.mayai`). Если **несколько** счётчиков — перечислить `id`, `name`, `site` и **попросить выбрать** один `id`. 4. **Период** — если не сказан, предложить по умолчанию, например **вчера − 29 дней … вчера** (без «сегодня» для стабильности данных) или уточнить у пользователя. 5. **Ежедневная разбивка** — API отчётов: - вариант А: `GET .../stat/v1/data` с группировкой по дню визита **`dimensions=ym:s:date`**, **`metrics`** по задаче (часто `ym:s:visits`, при необходимости `ym:s:pageviews`, `ym:s:users` — имена проверять в [справочнике](https://yandex.ru/dev/metrika/ru/stat/)); - вариант Б: `GET .../stat/v1/data/bytime` — если удобнее именно «по времени» (см. openapi в доке stat). 6. Вызвать API (или дать пользователю **одну** готовую команду с плейсхолдерами), распарсить JSON. 7. Если в ответе **`contains_sensitive_data": true`** — кратко предупредить про ограничение раскрытия данных. ### Как выглядит ответ человеку (шаблон) Агент пишет **короткое резюме**, затем **таблицу или список по дням** (дата → визиты / просмотры / и т.д.), без сырого JSON на экран целиком, если пользователь не просил сырой вывод. Пример формулировки: - «Счётчик: **LAYMI** (`id` …), сайт **blog.mayai.ru**, период **…**. Ниже визиты по дням. Данные из API Метрики, токен из конфига OpenClaw.» - Далее строки вида: `2025-03-01 — визиты: 120`, … - Примечание при 429: «Сработала квота отчётов; повтори через несколько минут» (`{baseDir}/docs/04-quotas.md`). ### Пример цепочки запросов (PowerShell, без секрета в логах чата) ```powershell # 1) Найти счётчик по подстроке (maya / mayai) curl.exe -s -G "https://api-metrika.yandex.net/management/v1/counters" ` --data-urlencode "search_string=maya" ` --data-urlencode "per_page=50" ` -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) # 2) Ежедневные визиты (подставь $cid из шага 1) curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" ` --data-urlencode "ids=$cid" ` --data-urlencode "dimensions=ym:s:date" ` --data-urlencode "metrics=ym:s:visits" ` --data-urlencode "date1=30daysAgo" ` --data-urlencode "date2=yesterday" ` --data-urlencode "sort=ym:s:date" ` -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) ``` Точные **`metrics`/`dimensions`** при спорных отчётах — только из официальной доки, не по памяти модели. --- ## Сценарий: «на какую страницу больше трафика?» Запрос про **страницы** — это снова **API отчётов** `GET .../stat/v1/data`, после того же **разрешения счётчика** (id / `defaultCounterId` / `search_string`), что и в сценарии выше. ### Смысл «трафика» - Чаще всего пользователь имеет в виду **просмотры страниц** (хиты): группировка по URL страницы + метрика просмотров. Тогда в одном запросе используется **только префикс `ym:pv:`** (визиты и хиты в основном наборе не смешивать). - Если нужны **входы / визиты с первой страницы** (лендинги), это другой отчёт: группировки уровня **визита** (`ym:s:...`), другие метрики — уточнить у пользователя или дать оба коротко («по просмотрам лидирует …, по визитам на входе …»), опираясь на [справочник группировок](https://yandex.ru/dev/metrika/ru/stat/). ### Типовой запрос (топ URL по просмотрам) Параметры (имена перепроверять в доке при смене версии API): - `dimensions` — URL страницы на уровне хита, например **`ym:pv:URL`**. - `metrics` — **`ym:pv:pageviews`** (и при необходимости ещё метрики из того же множества `ym:pv:`). - `sort` — по убыванию просмотров, в доке Метрики для сортировки по убыванию часто используется **`-`** перед метрикой (см. `{baseDir}/docs/05-reports-api-stat.md`). - `limit` — топ **10–20** URL, чтобы ответ был читаемым. - `date1` / `date2` — как в других сценариях (если не заданы — default или вопрос пользователю). ### Как выглядит ответ человеку Коротко: период, счётчик, что считали (**просмотры по URL**). Затем список: **URL → число просмотров** (топ N). Длинные URL можно обрезать визуально с «…», полный URL — по наведению или второй строкой при необходимости. ### Пример `curl` (PowerShell) ```powershell curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" ` --data-urlencode "ids=$cid" ` --data-urlencode "dimensions=ym:pv:URL" ` --data-urlencode "metrics=ym:pv:pageviews" ` --data-urlencode "sort=-ym:pv:pageviews" ` --data-urlencode "limit=15" ` --data-urlencode "date1=30daysAgo" ` --data-urlencode "date2=yesterday" ` -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) ``` Если API вернёт ошибку совместимости группировки и метрики — не «угадывать» замену, а свериться с актуальным openapi для `/stat/v1/data` на сайте Метрики. --- ## Маршрутизация: что дергать | Запрос пользователя | Куда | Файл | |---------------------|------|------| | Отчёт, метрики, период, сегменты | `GET .../stat/v1/data` (и др. из stat) | `{baseDir}/docs/05-reports-api-stat.md` | | Топ страниц, «куда больше трафика» | `stat/v1/data`, группировка URL (`ym:pv:`) | сценарий ниже, `{baseDir}/docs/05-reports-api-stat.md` | | Сырые логи, выгрузка | `management/v1/counter/{id}/logrequests...` | `{baseDir}/docs/06-logs-api.md` | | Список счётчиков, цели, настройки | `management/v1/...` | `{baseDir}/docs/08-management-quickstart.md` | | Загрузка расходов, CRM, офлайн | data-import | `{baseDir}/docs/07-data-import.md` | | 401/403, scope | OAuth | `{baseDir}/docs/03-auth-oauth.md`, `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md` | | 429 | Квоты | `{baseDir}/docs/04-quotas.md` | | «Что ещё спрашивают / не знаю какой отчёт» | Матрица намерений | `{baseDir}/docs/10-user-intents-matrix.md` | Смешанная задача: **сначала** `counters` или `defaultCounterId`, **потом** stat/logs. --- ## Железные правила API - Заголовок: **`Authorization: OAuth <access_token>`** (слово `OAuth` и пробел обязательны). - Хост: **`https://api-metrika.yandex.net`** - В одном запросе **stat** не смешивать **`ym:s:`** и **`ym:pv:`** в основных `metrics`/`dimensions` (детали в `{baseDir}/docs/05-reports-api-stat.md`). - Лимиты: до **20** метрик, **10** группировок в `/stat/v1/data`; **200 запросов / 5 мин** на этот endpoint на пользователя; Logs с IP — **10**/с. - Имена метрик/группировок **не выдумывать** — только из официального справочника (ссылки в `{baseDir}/docs/01-links-and-hub.md`). - После скачивания Logs — **`clean`**, квота хранилища **10 ГБ** на счётчик (`{baseDir}/docs/06-logs-api.md`). --- ## Формат ответа агента OpenClaw 1. Что сделано / что предлагается (1 фраза). 2. Откуда взяты токен и счётчик (конфиг / env / спросил у пользователя). 3. Команда или URL-шаблон **без секрета**. 4. Как проверить успех (HTTP 200, поля JSON). 5. Риски: квоты, `contains_sensitive_data`, 429. --- ## Карта файлов | Файл | Назначение | |------|------------| | `openclaw.plugin.json` | Контракт OpenClaw: `oauthToken`, `defaultCounterId`, `oauthClientId` | | `{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md` | Установка: OpenClaw, OAuth-галочки, TG, после ключа — с чего начать | | `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md` | Токен для людей | | `{baseDir}/docs/OPENCLAW-AGENT.md` | Установка: нет HOOK.md; PowerShell без ловушек кавычек | | GitHub: [REDACTED_SECRET] → `scripts/exchange-yandex-oauth-code.ps1` | Обмен `code` → token (в этом пакете не включён) | | `{baseDir}/docs/01`–`09` | Справка по разделам API | | `{baseDir}/docs/10-user-intents-matrix.md` | **Матрица вопросов пользователей → API** (ресёрч по примерам и пресетам) | Официальный хаб: https://yandex.ru/dev/metrika

path: .gitignore
content: # Эта папка не должна становиться git-репозиторием внутри zip для ClawHub.
# Если инициализируете git локально — не включайте .git в архив загрузки.


path: openclaw.plugin.json
content: {
  "id": "yandex-metrika-assistant",
  "name": "Yandex Metrika Assistant",
  "version": "1.0.0",
  "description": "Yandex Metrika Assistant — OpenClaw: API Яндекс.Метрики (stat, Logs, management, импорт, OAuth). Автоматизация аналитики и AI-агенты. Канал: https://t.me/maya_pro",
  "skills": ["."],
  "uiHints": {
    "oauthToken": {
      "label": "OAuth-токен Метрики",
      "help": "access_token Яндекса (metrika:read / metrika:write)",
      "sensitive": true
    },
    "defaultCounterId": {
      "label": "ID счётчика по умолчанию",
      "help": "Подставляется в ids=, если пользователь не указал счётчик"
    },
    "oauthClientId": {
      "label": "OAuth Client ID",
      "help": "Для ссылки authorize, если токена ещё нет"
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "oauthToken": {
        "type": "string",
        "description": "OAuth access_token Яндекса (metrika:read/write). Только секреты OpenClaw/окружение — не коммитить, не дублировать в чат."
      },
      "defaultCounterId": {
        "type": "integer",
        "description": "Если задан — подставляй в ids=/counterId, когда пользователь не указал счётчик."
      },
      "oauthClientId": {
        "type": "string",
        "description": "Опционально: Client ID приложения OAuth — для генерации ссылки authorize, если токена ещё нет."
      }
    }
  }
}


path: README.md
content: # ClawHub upload bundle — Yandex Metrika Assistant

Эта папка собрана **без** каталога `.git`, чтобы загрузка на [ClawHub](https://clawhub.ai) не ломалась из‑за известной проблемы «SKILL.md required» при наличии `.git` в архиве.

## Поля формы ClawHub

| Поле | Рекомендуемое значение |
|------|-------------------------|
| **Slug** | `yandex-metrika-assistant` |
| **Display name** | `Yandex Metrika Assistant` |

- Включите согласие с **MIT-0** на форме публикации (текст лицензии: https://spdx.org/licenses/MIT-0.html).
- Обязателен **`SKILL.md`** — он уже в корне.

## Содержимое архива

- `SKILL.md` — навык для OpenClaw
- `openclaw.plugin.json` — контракт плагина OpenClaw
- `docs/` — справка и инструкции (пути `{baseDir}/docs/...` в SKILL)

Скрипт обмена OAuth и полный `LICENSE` — в репозитории на GitHub (см. ссылку ниже).

## Как упаковать (Windows PowerShell)

Из каталога **родителя** этой папки (обязательно `\*`, не саму папку — иначе `SKILL.md` не окажется в корне zip):

```powershell
Compress-Archive -Path ".\clawhub-yandex-metrika-assistant\*" -DestinationPath ".\yandex-metrika-assistant-clawhub.zip" -Force
```

### Если валидация пишет «SKILL.md is required»

1. **В корне zip должен быть именно `SKILL.md`**, а не `какая-то-папка/SKILL.md`. Неправильно: архивировать папку целиком (`Compress-Archive -Path .\clawhub-yandex-metrika-assistant` без `\*`) — внутри получится одна вложенная папка, ClawHub файл не находит.
2. В архиве **не должно быть** каталога `.git` (см. [issue OpenClaw #32169](https://github.com/openclaw/openclaw/issues/32169)).
3. **Не используйте для упаковки** `tar -c -f ... .` из папки навыка без проверки: в zip может оказаться путь вида `./SKILL.md`; часть проверок ожидает ровно `SKILL.md`. После сборки откройте zip и убедитесь, что в корне есть `SKILL.md`.
4. Загружайте архив, собранный из **`clawhub-yandex-metrika-assistant`**, а не из всего репозитория `yandex-metrika-assistant` с вложенной структурой.

Исходный репозиторий с историей: https://github.com/Horosheff/yandex-metrika-assistant


path: docs/01-links-and-hub.md
content: # Точки входа и ссылки

Основано на хабе: https://yandex.ru/dev/metrika и https://yandex.ru/dev/metrika#articles

## Документация и продукт

| Назначение | URL |
|------------|-----|
| Хаб «API Метрики» | https://yandex.ru/dev/metrika |
| Документация (RU) | https://yandex.ru/dev/metrika/ru/ |
| Веб-интерфейс Метрики | https://metrika.yandex.ru/ |
| Справка Яндекс.Метрики | https://yandex.ru/support/metrica |

## OAuth и идентификация

| Назначение | URL |
|------------|-----|
| Создать OAuth-приложение (клиент) | https://oauth.yandex.ru/client/new |
| Создание приложения (диалог) | https://oauth.yandex.ru/?dialog=create-client-entry |
| Введение в OAuth Яндекса | https://yandex.ru/dev/id/doc/ru/concepts/ya-oauth-intro |

## Правовые и организационные

| Назначение | URL |
|------------|-----|
| Условия использования Метрики | https://yandex.ru/legal/metrica_termsofuse/ |

## Интеграции и сообщество

| Назначение | URL |
|------------|-----|
| Список платформ / коннекторы | https://metrika.yandex.ru/about/info/integrations |
| Telegram-чат | https://t.me/yandexmetrika |
| Блог Метрики | https://yandex.ru/blog/metrika |

## История и квоты (из хаба)

- Квоты: https://yandex.ru/dev/metrika/ru/intro/quotas
- История изменений API: https://yandex.ru/dev/metrika/ru/intro/changelog
- API отчётов — примеры: https://yandex.ru/dev/metrika/ru/stat/examples
- Logs API + ClickHouse (страница в доке Метрики): https://yandex.ru/dev/metrika/ru/logs/clickhouse-integration

## Доступ к счётчику (справка)

- Типы доступа: https://yandex.ru/support/metrica/general/access.html


path: docs/02-base-url-and-structure.md
content: # Базовый URL и структура API

Источник: https://yandex.ru/dev/metrika/ru/intro/method-call  
Версионирование: https://yandex.ru/dev/metrika/ru/intro/versions

## Протокол и хост

- Запросы только по **HTTPS**.
- Хост: **`api-metrika.yandex.net`**

## Шаблон запроса

```
<METHOD> https://api-metrika.yandex.net/<раздел_API>/<версия>/<имя_метода>.<формат_результата>?<параметры>
```

- **METHOD** — GET, POST, PUT, DELETE (в зависимости от ресурса).
- **раздел_API**:
  - `management` — API управления и часть операций **Logs API**
  - `stat` — API отчётов
  - `analytics` — API, совместимое с **Google Analytics Core Reporting API**
- **версия** — например `v1`, `v2` (указывать явно).
- **имя_метода** — путь ресурса.
- **формат_результата** — опционально; по умолчанию часто JSON.
- **параметры** — query и/или тело для POST/PUT.

## Примеры с версиями

```
https://api-metrika.yandex.net/stat/v1/data?id=...
https://api-metrika.yandex.net/stat/v2/data?id=...
```

## REST-модель

Ресурсы адресуются уникальными URL; операции: чтение (GET), запись (PUT), удаление (DELETE), добавление в коллекции (POST).

## Виды API (введение)

См. https://yandex.ru/dev/metrika/ru/

1. **API управления** — счётчики, цели, фильтры, доступы, представители и др.  
   https://yandex.ru/dev/metrika/ru/management/
2. **API импорта данных** — расходы, CRM, звонки, офлайн-конверсии, параметры посетителей.  
   https://yandex.ru/dev/metrika/ru/data-import/index
3. **API отчётов** — агрегированная статистика, сегментация.  
   https://yandex.ru/dev/metrika/ru/stat/
4. **Logs API** — неагрегированные данные.  
   https://yandex.ru/dev/metrika/ru/logs/


path: docs/03-auth-oauth.md
content: # Авторизация (OAuth)

Источник: https://yandex.ru/dev/metrika/ru/intro/authorization  
Быстрый старт (дублирует шаги получения токена): https://yandex.ru/dev/metrika/ru/intro/quick-start

## Требование

Для API Яндекс.Метрики нужен **OAuth-токен** Яндекса. Токен передаётся **в каждом запросе** в заголовке:

```http
Authorization: OAuth <token>
```

Пример из документации (управление):

```http
GET /management/v1/counters HTTP/1.1
Host: api-metrika.yandex.net
Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037
Content-Type: application/x-yametrika+json
```

В примерах быстрого старта для JSON также используется `Content-Type: application/json`.

## Ошибки

- **401 Unauthorized** — нет токена, неверный формат заголовка или недействительный токен.
- **403 Access denied** — см. раздел «Возможные проблемы» ниже.

## Создание приложения и получение токена

1. Создать приложение: https://oauth.yandex.ru/?dialog=create-client-entry  
   Тип: **«Для доступа к API или отладки»**.
2. Заполнить название, почту, **доступ к данным** (scopes).
3. Скопировать **Client ID**.
4. Открыть в браузере (implicit flow):

```
https://oauth.yandex.ru/authorize?response_type=token&client_id=<application_id>
```

5. Скопировать выданный **токен** со страницы.

**Важно:** владелец токена — аккаунт, под которым открыли ссылку авторизации, а не обязательно владелец приложения.

## Scopes (доступы приложения)

| Scope | Назначение |
|--------|------------|
| `metrika:read` | Статистика, чтение параметров своих и доверенных счётчиков, список счётчиков |
| `metrika:write` | Создание/изменение счётчиков, загрузка данных |
| `metrika:expenses` | Загрузка расходов в счётчики |
| `metrika:user_params` | Загрузка параметров посетителей |
| `metrika:offline_data` | Офлайн-данные: CRM, офлайн-конверсии, звонки |

Если указан **`metrika:write`**, отдельно **`metrika:expenses`**, **`metrika:user_params`**, **`metrika:offline_data`** не обязательны.

## Организации (porg / логины организации)

Добавить в права приложения **`passport:business`**, если нужен токен от организации.

## 403 — типичные причины

**Приложение:** нет доступа к Метрике — для чтения отчётов и параметров счётчика нужен `metrika:read`, для управления и загрузок — `metrika:write`.

**Токен:** истёк срок; сменили пароль на аккаунте; токен выдан другому пользователю или другому `client_id`.

**Метрика:** у владельца токена нет прав на счётчик (нужен владелец или гостевой просмотр/редактирование — см. справку по доступу).

**Запрос:** заголовок `Authorization` задан неверно или не передаётся.

## Безопасность

Не передавать токен третьим лицам; хранить в секретах, не коммитить в репозиторий.


path: docs/04-quotas.md
content: # Квотирование

Источник: https://yandex.ru/dev/metrika/ru/intro/quotas  
Уточнение лимитов отчётов: https://yandex.ru/dev/metrika/ru/intro/changelog (17.12.2025)

## Ответ при превышении

- HTTP **429 Too Many Requests**
- В теле ответа — информация о **типе** превышенной квоты

## Таблица ограничений

| Ограничение | Квота | Разблокировка |
|-------------|--------|----------------|
| Запросы с одного **IP** (API в целом) | **30** в секунду | Когда за последнюю секунду запросов станет **< 30** |
| Запросы с одного **IP** (**Logs API**) | **10** в секунду | Когда за последнюю секунду **< 10** |
| Параллельные запросы на пользователя (`user_login`) | **3** | Когда одновременных запросов **< 3** |
| Запросы на пользователя в сутки | **5000** | В **00:00 по GMT** |
| Запросы к **API отчётов** URL вида `/stat/v1/data/` | **200 за 5 минут** на пользователя | Через **5 минут** после превышения |
| Запросы к отчётам в **веб-интерфейсе** | **400 за 5 минут** | (аналогично по смыслу ожидания) |
| Добавление **представителей** на один счётчик | **3 в час** | В начале каждого часа (**00 минут**) |

## Лимиты на доступ к одному счётчику

Интенсивность считается **отдельно по группам методов**:

- **`client_read`** — чтение параметров счётчика/аккаунта; относится к методам **API управления** (чтение).
- **`client_write`** — сохранение параметров счётчика/аккаунта.
- **`report_read`** — данные отчётов Метрики: **API отчётов**, конструктор, **GA-совместимый API**.

(Детали по каждой группе — в полном тексте статьи про квоты на сайте Яндекса.)

## Практика для интеграций

- Разделяйте нагрузку: не дергать `/stat/v1/data/` в цикле без задержек — учитывать **200/5 мин**.
- Logs API — отдельный лимит **10 req/s** с IP.
- При 429 — exponential backoff и повтор после интервала из таблицы.


path: docs/05-reports-api-stat.md
content: # API отчётов (stat)

Введение: https://yandex.ru/dev/metrika/ru/stat/  
Справочник таблицы: https://yandex.ru/dev/metrika/ru/stat/openapi/data  
Примеры: https://yandex.ru/dev/metrika/ru/stat/examples  
Сегментация: https://yandex.ru/dev/metrika/ru/stat/segmentation  
Семплирование: https://yandex.ru/dev/metrika/ru/stat/sampling  
Шаблоны отчётов (preset): https://yandex.ru/dev/metrika/ru/stat/presets

## Концепции

- **Группировка (dimension)** — атрибут визита/хита, по которому агрегируют данные. В запросе: параметр **`dimensions`** (несколько через запятую).
- **Метрика (metric)** — числовая величина по визитам/хитам. В запросе: **`metrics`** (несколько через запятую).
- Отчёт **без группировок** — суммарный результат по метрикам.

### Префиксы (совместимость в одном запросе)

- **`ym:s:`** — визиты  
- **`ym:pv:`** — хиты  

В **одном** запросе нельзя смешивать разные префиксы в основном наборе dimensions/metrics и указывать больше одного «множества» (см. доку по сегментации).

В параметре **`filters`** допускаются другие префиксы — в доке приведён пример с `ym:s:` в dimensions/metrics и `ym:pv:` в фильтре.

## Эндпоинты

| Вид | Метод |
|-----|--------|
| Таблица | `GET https://api-metrika.yandex.net/stat/v1/data` |
| Drill down | `GET .../stat/v1/data/drilldown` |
| По времени | `GET .../stat/v1/data/bytime` |
| Сравнение (таблица) | `GET .../stat/v1/data/comparison` |
| Сравнение (drilldown) | `GET .../stat/v1/data/comparison/drilldown` |

Документация по каждому — в разделе stat на сайте (openapi-страницы).

## Формат ответа

- Кодировка: **UTF-8**
- Формат: **JSON** (по умолчанию) или **CSV** — задаётся суффиксом в пути, например:

```
GET https://api-metrika.yandex.net/stat/v1/data.csv?id=...&metrics=...&dimensions=...
```

Пример из документации:

```
https://api-metrika.yandex.net/stat/v1/data.csv?id=44147844&metrics=ym:s:avgPageViews&dimensions=ym:s:operatingSystem&limit=5
```

## GET /stat/v1/data — основные query-параметры

Источник: openapi «Таблица».

| Параметр | Описание / лимиты |
|----------|-------------------|
| `ids` | ID счётчиков через запятую (integer[]) |
| `metrics` | Список метрик через запятую. **Лимит: 20 метрик** |
| `dimensions` | Группировки через запятую. **Лимит: 10 группировок** |
| `date1`, `date2` | `YYYY-MM-DD` или `today`, `yesterday`, `ndaysAgo`. Defaults в доке: часто `6daysAgo` и `today` |
| `filters` | Сегментация. До **10** уникальных измерений/метрик в фильтре, до **20** отдельных фильтров, длина строки условия до **10 000** символов, до **100** значений в одном условии |
| `limit` | Строк на страницу. **Макс. 100 000**, default `100` |
| `offset` | Индекс первой строки, **начиная с 1**, default `1` |
| `accuracy` | Размер выборки (семплирование) |
| `proposed_accuracy` | Если `true`, API может повысить accuracy до рекомендуемого |
| `preset` | Шаблон отчёта |
| `sort` | Сортировка по метрикам/группировкам; `-` перед именем — по убыванию |
| `timezone` | `±hh:mm` в диапазоне [-23:59; +23:59]; `+` в URL как `%2B`. По умолчанию — часовой пояс счётчика |
| `include_undefined` | boolean — строки с неопределённой первой группировкой |
| `direct_client_logins` | Логины клиентов Директа через запятую (отчёты по Директ-расходам) |
| `lang`, `pretty`, `callback` | Язык, форматирование JSON, JSONP |

Также доступны `id` в виде `id=44147844` в примерах (идентификатор счётчика) — в справочнике основной параметр списка счётчиков: **`ids`**.

## Раскрытие данных и приватность

- Часть данных (например соцдем) выдаётся **только если в выборке больше 10 посетителей**.
- В ответе API смотреть **`contains_sensitive_data`**: если **`true`**, данные с ограничениями.

Справка: https://yandex.ru/support/metrica/reports/report-general.html?lang=ru#privacy

## Версии stat

Поддерживаются `v1`, `v2` и др.; новым интеграциям — актуальная версия (см. `02-base-url-and-structure.md`).


path: docs/06-logs-api.md
content: # Logs API (неагрегированные данные)

Введение: https://yandex.ru/dev/metrika/ru/logs/  
Сценарий (quick start): https://yandex.ru/dev/metrika/ru/logs/practice/quick-start  
Авторизация (раздел logs): https://yandex.ru/dev/metrika/ru/logs/ (ссылка на intro/authorization)  
Квоты logs: https://yandex.ru/dev/metrika/ru/intro/quotas + общий раздел «Ограничения» на странице logs

## Назначение

Выгрузка **неагрегированных** данных, собираемых Метрикой; для самостоятельной обработки и нестандартной аналитики.

## Авторизация и квоты

- В каждом запросе — **OAuth-токен** (как для остального API).
- Отдельные **квоты Logs API**: с одного IP **10 запросов в секунду** (см. `04-quotas.md`).
- Общие суточные и параллельные лимиты пользователя также применяются.

## Хранение и актуальность

- Данные визитов **дозаполняются**; ~**99% визитов** завершаются в течение **3 дней** после начала.
- Статистика за **текущий день** может быть неполной — рекомендуют запрашивать **со вчера и раньше**.
- **Общий объём** данных логов на **один счётчик** (включая не удалённые логи): **10 ГБ**.

## Ограничения запросов (из введения logs)

| Ограничение | Значение |
|-------------|----------|
| Период в одном запросе | **Не более 1 года** |
| Длина параметра `fields` (список полей) | **Не более 3000 символов** |
| Квота хранилища логов на счётчик | **10 ГБ** суммарно (подготовленные + не удалённые) |

Освобождение места: регулярно удалять подготовленные и скачанные логи — метод **clean** (ниже).

Текущее занятое место: **GET** список log requests и суммировать поле **`size`** в ответах.  
Список: https://yandex.ru/dev/metrika/ru/logs/openapi/getLogRequests  
Clean: https://yandex.ru/dev/metrika/ru/logs/openapi/clean

## Увеличение квоты

Подключить **Метрику Про**: https://yandex.ru/support/metrica/pro/intro.html?lang=ru

## Сценарий работы (management + logs)

База URL: `https://api-metrika.yandex.net/management/v1/...`

1. **Оценка** (опционально):  
   `GET /counter/{counterId}/logrequests/evaluate`  
   https://yandex.ru/dev/metrika/ru/logs/openapi/evaluate

2. **Создать задание на выгрузку**:  
   `POST /counter/{counterId}/logrequests`  
   https://yandex.ru/dev/metrika/ru/logs/openapi/createLogRequest  
   Сохранить **`request_id`**.

3. **Статус**:  
   `GET /counter/{counterId}/logrequest/{requestId}`  
   https://yandex.ru/dev/metrika/ru/logs/openapi/getLogRequest  
   Когда статус **`processed`** — файл готов.

4. **Скачать часть**:  
   `GET /counter/{counterId}/logrequest/{requestId}/part/{partNumber}/download`  
   https://yandex.ru/dev/metrika/ru/logs/openapi/download

5. **Очистить** после выгрузки:  
   `POST /counter/{counterId}/logrequest/{requestId}/clean`  
   https://yandex.ru/dev/metrika/ru/logs/openapi/clean

Запросы обрабатываются **в очереди**; новый запрос в конец. Если статус **`created`**, ждать. При неудаче — повторить в другое время.

## ClickHouse / облако

Страница в доке Метрики: https://yandex.ru/dev/metrika/ru/logs/clickhouse-integration  

Практическая инструкция выгрузки (Yandex Cloud / DataLens):  
https://cloud.yandex.ru/docs/datalens/tutorials/data-from-metrica-yc-visualization#uploading-data-logs-api

## Расхождения с интерфейсом и числа с плавающей точкой

В интерфейсе — дополнительные алгоритмы обработки. В логах числа по **IEEE 754**; для ряда полей используются **коэффициенты** (см. FAQ на странице logs), например:

| Поле | Коэффициент |
|------|-------------|
| `ym:s:purchaseRevenue` | 1 (также в API отчётов) |
| `ym:s:goalsPrice` | 1000 |
| `ym:s:productsPrice`, `ym:s:impressionsProductPrice`, `ym:s:purchaseTax`, `ym:s:eventsProductPrice` | 1 000 000 |

## Переименования полей (changelog 15.10.2025)

В **визитах**:

- `ym:s:eventsProduct` → **`ym:s:product`**
- `ym:s:products` → **`ym:s:purchasedProduct`**

Старые имена пока выгружаются, поддержка будет прекращена.

В **событиях**: добавлены поля с массивами по e-commerce и звонкам; офлайн-конверсии — поле **`ym:pv:goalsID`**.

Для Метрики Про в визитах: поле **`ym:s:isRobotPro`** (и в Data Streaming — см. changelog).


path: docs/07-data-import.md
content: # API импорта данных

Введение: https://yandex.ru/dev/metrika/ru/data-import/index

Импорт дополняет данные счётчика: сквозная аналитика, расходы по каналам, связь офлайн-действий с визитами и т.д.

## Типы импорта и ссылки в документацию

### Офлайн-конверсии

Действия пользователя вне сайта (оплата после заявки и т.п.), связь с визитами.

- Подробнее: https://yandex.ru/dev/metrika/ru/data-import/management/offline-conv

### Чаты

Чаты в мессенджерах, связь с визитами; цели и отчёты.

- Подробнее: https://yandex.ru/dev/metrika/ru/data-import/management/chats-transfer-data

### CRM

Клиенты и заказы.

- Подробнее: https://yandex.ru/dev/metrika/ru/data-import/data-import/contacts

### Звонки

- Подробнее: https://yandex.ru/dev/metrika/ru/data-import/management/calls

### Расходы

- Multipart: https://yandex.ru/dev/metrika/ru/data-import/management/openapi/expense/uploadMultipart

### Параметры посетителей

- Upload: https://yandex.ru/dev/metrika/ru/data-import/management/openapi/user_params/upload

## Права

Для загрузок обычно нужен **`metrika:write`** (или узкие scopes из `03-auth-oauth.md`).

## Связанные темы в changelog

- **Measurement Protocol**: см. https://yandex.ru/dev/metrika/ru/data-import/measurement-about  
- Параметры счётчика **`measurement_tokens`**, **`measurement_enabled`** (обновление API управления, см. `09-changelog-highlights.md`).


path: docs/08-management-quickstart.md
content: # API управления — быстрый старт и счётчики

Быстрый старт (общий): https://yandex.ru/dev/metrika/ru/intro/quick-start  
Введение management: https://yandex.ru/dev/metrika/ru/management/

## Список счётчиков

```
GET https://api-metrika.yandex.net/management/v1/counters
Authorization: OAuth <token>
```

Пример curl из документации:

```bash
curl -i -X GET 'https://api-metrika.yandex.net/management/v1/counters' \
  -H 'Authorization: OAuth 05dd3dd8...'
```

Ответ содержит массив **`counters`** с полями вроде `id`, `name`, `site`, `permission`, `status` и т.д.

### Полезные query-параметры (справочник counters)

Документация: https://yandex.ru/dev/metrika/ru/management/openapi/counter/counters

| Параметр | Назначение |
|----------|------------|
| `per_page` | Количество счётчиков (макс. **10 000** за запрос, default **1000**) |
| `offset` | С какого номера начать (1-based, макс. смещение связано с лимитом 100 000 счётчиков на пользователя) |
| `permission` | `own`, `view`, `edit` (можно несколько через запятую) |
| `counter_ids` | Явный список ID |
| `field` | Доп. поля объекта через запятую, без пробелов: например `goals,mirrors,grants,filters,operations,counter_flags,measurement_tokens` |
| `favorite`, `label_id`, `search_string`, `reverse`, `robots` | Фильтры и сортировка — см. openapi |

## Пример: создать цель

```
POST https://api-metrika.yandex.net/management/v1/counter/{counterId}/goals
Authorization: OAuth <token>
Content-Type: application/json
```

Документация метода: https://yandex.ru/dev/metrika/ru/management/openapi/goal/addGoal  

Пример из quick-start — цель типа **MessengerGoal** (`messenger`), условие с `url` (например `whatsapp`):

```bash
curl -i -X POST 'https://api-metrika.yandex.net/management/v1/counter/XXX/goals' \
  -H 'Authorization: OAuth 05dd3dd8...' \
  -H 'Content-Type: application/json' \
  -d '{
    "goal": {
      "id": 0,
      "name": "MyMessengerGoal",
      "type": "messenger ",
      "conditions": [{
        "type": "messenger",
        "url": "whatsapp"
      }]
    }
  }'
```

(В ответе `type` нормализуется к `"messenger"`.)

## Область API управления

Счётчики (CRUD), цели, операции, фильтры, доступы, представители и др. — см. дерево методов в разделе **management** на сайте разработчиков.

### Фильтры доступа (changelog 02.10.2024)

Методы access filter, например:

- create: https://yandex.ru/dev/metrika/ru/management/openapi/access_filter/createAccessFilter  
- delete, get, list, update — см. changelog в `09-changelog-highlights.md` или поиск по `access_filter` в доке.


path: docs/09-changelog-highlights.md
content: # История изменений API — выжимка для разработки

Полная лента: https://yandex.ru/dev/metrika/ru/intro/changelog  

Ниже — пункты, полезные при проектировании интеграций (не дублирует весь changelog).

## 2025

### 17 декабря 2025

- Обновлены **квоты**: **200** запросов за **5 минут** к API отчётов с URL **`/stat/v1/data/`**; **400** за **5 минут** к отчётам в интерфейсе.  
  См. также `04-quotas.md`.

### 15 октября 2025

- **Logs API / события**: новые поля (массивы e-commerce, звонки); офлайн-конверсии через **`ym:pv:goalsID`**.
- **Logs API / визиты**: переименования — `ym:s:eventsProduct` → **`ym:s:product`**, `ym:s:products` → **`ym:s:purchasedProduct`**; старые имена временно поддерживаются, затем будут отключены.

### 24 июня 2025

- **Метрика Про**: в визитах логов — **`ym:s:isRobotPro`**; также в Data Streaming (справка Pro).

### 24 февраля 2025

- Новые **метрики** и **группировки** для отчёта «Загрузки файлов» (ссылки в полном changelog на stat/metrics и stat/attributes).

## 2024

### 11 октября 2024

- Управление счётчиками: параметры **`measurement_tokens`**, **`measurement_enabled`** (Measurement Protocol).  
  См. https://yandex.ru/dev/metrika/ru/data-import/measurement-about

### 2 октября 2024

- API **фильтров доступа** (создание, удаление, получение, список, изменение) — пути `.../access_filter/...` в доке management.

### 3 сентября 2024

- **Мониторинг доступности сайтов** в Метрике закрыт.

### 31 июля 2024

- Новые группировки по источнику трафика в **рекламных расходах**: `ym:ev:TrafficSource`, `ym:ev:SourceEngine`.

### 24 июля 2024

- Новые группировки по **событиям** и **дате/времени** (URL события, параметры событий, точность даты и т.д.) — см. полный changelog со ссылками на stat/attributes.

## Рекомендация

Перед релизом интеграции сверять типы полей логов, названия metrics/dimensions и квоты с **актуальной** страницей changelog и openapi-справочниками.


path: docs/10-user-intents-matrix.md
content: # Типовые вопросы пользователей → API Метрики (матрица для агента)

Собрано по структуре [примеров API отчётов](https://yandex.ru/dev/metrika/ru/stat/examples), [шаблонов (preset)](https://yandex.ru/dev/metrika/ru/stat/presets) и разделам **management / logs / import**. Имена **`metrics`/`dimensions`/`filters`** агент подбирает только из **актуального справочника** Метрики, не «с головы».

**Общий порядок:** токен → `ids` счётчика → `date1`/`date2` → `GET /stat/v1/data` (или `bytime` / `comparison` / `drilldown`) → интерпретация `contains_sensitive_data`.

Для фильтров с **русскими названиями** городов и т.п. в запросе указывать **`lang=ru`** (см. примеры в доке).

---

## A. Трафик и динамика

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Сколько визитов/посетителей за период | `stat/v1/data`, `metrics=ym:s:visits`, `ym:s:users` (или пресет посещаемости) | Период явно; по умолчанию в примерах часто 7 дней |
| Динамика по дням / «график за месяц» | `stat/v1/data/bytime` или `dimensions=ym:s:date` + метрики | См. [пример «просмотры по дням»](https://yandex.ru/dev/metrika/ru/stat/examples#query4) |
| Сравни два периода / вчера и позавчера | `stat/v1/data/comparison` | [Сравнение сегментов](https://yandex.ru/dev/metrika/ru/stat/examples#comparison) |
| Падение/рост трафика — почему | Несколько запросов: источники + география + устройства за два окна | Косвенный анализ, API даёт числа |
| Исключить роботов | `filters=... AND ym:s:isRobot=='No'` | [Пример](https://yandex.ru/dev/metrika/ru/stat/examples#robots) |

---

## B. Источники, UTM, реклама

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Откуда приходят / источники сводка | `preset=sources_summary` | [Пример](https://yandex.ru/dev/metrika/ru/stat/examples#ex1) |
| Органика / поисковики / прямой / рефералы | `dimensions` по типу источника + `filters` | [Типы источников](https://yandex.ru/dev/metrika/ru/stat/examples#ex0) |
| Какие поисковые системы / фразы | `preset=sources_search_phrases` или группировки по поиску | [Поисковые фразы](https://yandex.ru/dev/metrika/ru/stat/examples#ex3) |
| UTM-метки, кампании, объявления | Пресеты раздела **Источники** или явные dimensions UTM | [Источники (presets)](https://yandex.ru/dev/metrika/ru/stat/presets/preset_sources) |
| Яндекс Директ, сводка по рекламе | Пресеты **Директ** | [preset_direct](https://yandex.ru/dev/metrika/ru/stat/presets/preset_direct) |
| Рекламные расходы (загруженные в Метрику) | Пресет **Рекламные расходы** + при необходимости импорт | [preset_expenses](https://yandex.ru/dev/metrika/ru/stat/presets/preset_expenses), `docs/07-data-import.md` |
| Эксперименты Директа | Пример «сегменты эксперимента» | [dim-metrics2](https://yandex.ru/dev/metrika/ru/stat/examples#dim-metrics2) |

---

## C. Аудитория: география, демография, устройства

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Страны, города, регионы | Пресеты **Посетители → География** или `dimensions` региона | Фильтр по городу: [пример СПб](https://yandex.ru/dev/metrika/ru/stat/examples#ex2); `lang=ru` для русских названий |
| Мобильные vs десктоп / планшеты | `comparison` мобильный / не мобильный | [Пример](https://yandex.ru/dev/metrika/ru/stat/examples#comparison2) |
| ОС, браузеры | `preset=tech_platforms`, `dimensions=ym:s:browser` и т.д. | [Браузеры](https://yandex.ru/dev/metrika/ru/stat/examples#ex4) |
| Язык браузера | Группировки уровня визита из справочника | Сверять имя в доке |
| Новые vs вернувшиеся | Метрики/сегментация «новый посетитель» (справочник) | См. разделы preset **Посетители** |

Соцдем (пол, возраст) в API может быть **ограничен** из-за порога выборки — смотреть **`contains_sensitive_data`**.

---

## D. Контент и поведение на сайте

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Топ страниц по просмотрам | `ym:pv:URL` + `ym:pv:pageviews`, сортировка | Сценарий в `SKILL.md` |
| Входные страницы / лендинги | Группировки уровня **визита** (вход), не путать с хитами | Справочник **Содержание** |
| Глубина просмотра, время, отказы | Метрики визита из справочника | Фильтр «глубина > N»: [пример](https://yandex.ru/dev/metrika/ru/stat/examples#page-view) |
| Поиск по сайту | Пресеты **Содержание** | [preset_content](https://yandex.ru/dev/metrika/ru/stat/presets/preset_content) |
| Загрузки файлов | Метрики/группировки «Загрузки» (обновления API 2025) | `docs/09-changelog-highlights.md` |
| Контентная аналитика (статьи, авторы, рубрики) | `preset=publishers_*` | [Примеры](https://yandex.ru/dev/metrika/ru/stat/examples#ex5) |

---

## E. Цели, конверсии, деньги

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Конверсия по цели / сколько достигли цели | Метрики целей в `stat/v1/data` + `filters` по цели | [Пример конверсии](https://yandex.ru/dev/metrika/ru/stat/examples#conv), несколько целей: [conv-mult](https://yandex.ru/dev/metrika/ru/stat/examples#conv-mult) |
| Список целей счётчика, id цели | `GET .../management/v1/counter/{id}/goals` | `docs/08-management-quickstart.md` |
| Создать / изменить цель | `POST`/`PUT` goals в management | OpenAPI в доке management |
| E-commerce: заказы, товары, выручка | Если данные передаются в Метрику — метрики ecommerce из справочника | [Справка ecommerce](https://yandex.ru/support/metrica/ru/ecommerce/data.html); пресеты монетизации при необходимости |

---

## F. Сегментация и «дрельдаун»

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Только органика из Москвы | `filters` на источник + регион | Комбинировать условия, `lang=ru` |
| Сложные условия | Параметр `filters`, лимиты длины и числа условий | `docs/05-reports-api-stat.md`, [сегментация](https://yandex.ru/dev/metrika/ru/stat/segmentation) |
| Дерево отчёта (как в интерфейсе) | `stat/v1/data/drilldown` | [Пример ОС](https://yandex.ru/dev/metrika/ru/stat/examples#drilldown1) |

---

## G. Выгрузка, точность, лимиты

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| В Excel / CSV | Суффикс `.csv` в пути `.../data.csv?...` | `docs/05-reports-api-stat.md` |
| Данные «как в интерфейсе» не сходятся | Объяснить семплирование (`accuracy`), таймзону (`timezone`), задержку обработки | Logs vs отчёты — см. FAQ в `docs/06-logs-api.md` |
| Слишком долго / 429 | Квоты, реже дергать `/stat/v1/data/` | `docs/04-quotas.md` |

---

## H. Сырые данные и импорт (продвинутые)

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Выгрузить сырые визиты/хиты | Logs API: create → poll → download → **clean** | `docs/06-logs-api.md` |
| Связать с ClickHouse | Интеграция из доки | `docs/06-logs-api.md` |
| Загрузить расходы на рекламу | Импорт расходов (multipart) | `docs/07-data-import.md` |
| Офлайн-конверсии, CRM, звонки | Импорт офлайн / CRM / calls | `docs/07-data-import.md` |

---

## I. Управление счётчиком и доступы

| Как могут спросить | Что делать | Примечание |
|--------------------|------------|------------|
| Какие счётчики есть / id сайта | `GET .../management/v1/counters` | `search_string`, `docs/08-management-quickstart.md` |
| Выдать доступ коллеге | Grants / представители в management | Справка по доступам + OpenAPI |
| Счётчик не собирает данные | `GET` параметры счётчика, `code_status`, проверка кода на сайте | Частично [справка Метрики](https://yandex.ru/support/metrica/), не всё через API |

---

## J. Что пользователи спрашивают, но API отчётов не заменяет полностью

| Тема | Как отвечать агенту |
|------|---------------------|
| **Вебвизор** (записи сессий, карты кликов) | В основном интерфейс Метрики; в API — ограниченно, не обещать полный паритет |
| **Онлайн в реальном времени** | Уточнить: в UI есть «сейчас»; в отчётном API — задержки и агрегация по правилам Метрики |
| **SEO-аудит «сделай за меня»** | API даёт метрики; интерпретация и рекомендации — зона аналитика, не самого API |
| **Юридическая интерпретация GDPR** | Отсылка к политике Яндекса и настройкам счётчика |
| **Почему упали продажи вне сайта** | Метрика не видит всё; только связанные данные и импорты |

---

## Ключевые URL

- Примеры запросов: https://yandex.ru/dev/metrika/ru/stat/examples  
- Шаблоны отчётов: https://yandex.ru/dev/metrika/ru/stat/presets  
- Сегментация: https://yandex.ru/dev/metrika/ru/stat/segmentation  
- Хаб API: https://yandex.ru/dev/metrika  


path: docs/EXAMPLES.md
content: # Примеры запросов к API (ручные и для отладки)

Перед вызовами нужны **OAuth-токен** и **id счётчика**. Токен не вставляйте в публичные репозитории и чаты.

Удобно задать переменную окружения:

```powershell
$env:YANDEX_METRIKA_OAUTH_TOKEN = "<ваш_токен>"
$cid = "99223440"   # подставьте свой counter id
```

Заголовок для всех запросов к `api-metrika.yandex.net`:

```http
Authorization: OAuth <access_token>
```

### PowerShell: если «ломаются кавычки» с curl

Не вставляйте токен из чата в середину строки с кавычками. Задайте **`$env:YANDEX_METRIKA_OAUTH_TOKEN`** отдельно (из секрета), затем:

```powershell
$h = @{ Authorization = 'OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN }
Invoke-RestMethod -Uri 'https://api-metrika.yandex.net/management/v1/counters?per_page=10' -Headers $h
```

Или одна строка **curl** без вложенных кавычек вокруг токена:

```powershell
curl.exe -s -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) 'https://api-metrika.yandex.net/management/v1/counters?per_page=10'
```

Для агента OpenClaw: см. также [`OPENCLAW-AGENT.md`](./OPENCLAW-AGENT.md).

---

## 1. Список доступных счётчиков

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/management/v1/counters" `
  --data-urlencode "per_page=50" `
  -H "Authorization: OAuth $env:YANDEX_METRIKA_OAUTH_TOKEN" | ConvertFrom-Json | Select-Object -ExpandProperty counters | Format-Table id, name, site
```

Поиск по подстроке (название или домен):

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/management/v1/counters" `
  --data-urlencode "search_string=blog" `
  --data-urlencode "per_page=20" `
  -H "Authorization: OAuth $env:YANDEX_METRIKA_OAUTH_TOKEN"
```

---

## 2. Визиты по дням за последние 30 дней

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:s:date" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  --data-urlencode "sort=ym:s:date" `
  -H "Authorization: OAuth $env:YANDEX_METRIKA_OAUTH_TOKEN"
```

---

## 3. Топ страниц по просмотрам (хиты)

В одном запросе используется только префикс **`ym:pv:`**.

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:pv:URL" `
  --data-urlencode "metrics=ym:pv:pageviews" `
  --data-urlencode "sort=-ym:pv:pageviews" `
  --data-urlencode "limit=15" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H "Authorization: OAuth $env:YANDEX_METRIKA_OAUTH_TOKEN"
```

---

## 4. Отчёт по шаблону (preset) — «источники, сводка»

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "preset=sources_summary" `
  --data-urlencode "date1=7daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H "Authorization: OAuth $env:YANDEX_METRIKA_OAUTH_TOKEN"
```

Другие пресеты: [шаблоны в доке Метрики](https://yandex.ru/dev/metrika/ru/stat/presets).

---

## 5. Выгрузка в CSV

Добавьте суффикс **`.csv`** к пути метода:

```
https://api-metrika.yandex.net/stat/v1/data.csv?ids=...&metrics=...&dimensions=...
```

---

## 6. Обмен кода OAuth на токен (authorization code)

Скрипт в репозитории: [`exchange-yandex-oauth-code.ps1`](https://github.com/Horosheff/yandex-metrika-assistant/blob/main/scripts/exchange-yandex-oauth-code.ps1).

Пошаговая выдача токена в браузере: [`INSTRUCTION-GET-TOKEN-RU.md`](./INSTRUCTION-GET-TOKEN-RU.md).

---

## Ограничения

- Квоты: см. [`docs/04-quotas.md`](./04-quotas.md).
- Имена метрик и группировок — только из [официального справочника](https://yandex.ru/dev/metrika/ru/stat/).


path: docs/INSTALL-FOR-HUMANS-RU.md
content: # Установка Yandex Metrika Assistant — для человека

Читайте **по порядку**. Сначала ставим навык и приложение в Яндексе, потом получаете токен и ключ в OpenClaw. Вопросы по сценарию — [**канал поддержки в Telegram**](https://t.me/maya_pro).

---

## Шаг 1. Установите навык / плагин в OpenClaw

1. Склонируйте репозиторий или скачайте архив:
   ```bash
   git clone https://github.com/Horosheff/yandex-metrika-assistant.git
   ```
2. Установите как **плагин** (рекомендуется, в корне есть `openclaw.plugin.json`):
   ```bash
   openclaw plugins install ./yandex-metrika-assistant
   ```
   Либо скопируйте папку в каталог навыков и используйте `openclaw skills install …` — как принято в вашей среде.
3. В конфиге OpenClaw **включите** плагин `yandex-metrika-assistant` в `plugins.entries` (плагины из workspace часто выключены по умолчанию — включите явно).
4. Перезапустите gateway при необходимости: `openclaw gateway restart`.
5. Назначьте навык нужному агенту (как у вас принято в `skills` / профиле агента).

> Файл **`HOOK.md` не нужен** — это навык + плагин, не hook. Подробности: [`OPENCLAW-AGENT.md`](./OPENCLAW-AGENT.md).

---

## Шаг 2. Создайте приложение в Яндекс OAuth и отметьте доступы к Метрике

1. Откройте [oauth.yandex.ru](https://oauth.yandex.ru/) → создайте приложение.
2. Тип: **«Для доступа к API или отладки»** (или аналог в интерфейсе).
3. Платформа: **Веб-сервисы**. **Redirect URI** (строго так):
   ```text
   https://oauth.yandex.ru/verification_code
   ```
4. В блоке доступа к **Яндекс.Метрике** отметьте галочки — в зависимости от задач:

| Задача | Что включить в приложении (как в кабинете OAuth) |
|--------|---------------------------------------------------|
| Смотреть отчёты, статистику | **Получение статистики, чтение параметров своих и доверенных счётчиков** |
| Менять счётчики, цели, настройки | **Создание счётчиков, изменение параметров своих и доверенных счётчиков** |
| Грузить расходы на рекламу | **Загрузка расходов** |
| Параметры посетителей | **Загрузка параметров пользователей** |
| CRM, офлайн-конверсии, звонки | **Загрузка офлайн данных (данные из CRM, офлайн конверсии, звонки)** |

Для большинства сценариев «спросить Метрику у AI» достаточно **чтения + записи** (первые две строки). Остальные — если реально грузите данные в Метрику.

5. Сохраните приложение и скопируйте **Client ID**.

Подробнее про `scope` и ссылки авторизации: [`INSTRUCTION-GET-TOKEN-RU.md`](./INSTRUCTION-GET-TOKEN-RU.md).

---

## Шаг 3. Канал поддержки

Вопросы по установке, OpenClaw, Make.com и нейросетям:  
**Telegram — [https://t.me/maya_pro](https://t.me/maya_pro)** ([@maya_pro](https://t.me/maya_pro)).

Не присылайте **токены и пароли** в открытый чат — только в личку доверенному админу или через настройки секретов OpenClaw.

---

## Шаг 4. Получите OAuth-токен и добавьте ключ в OpenClaw

1. Пройдите выдачу токена по инструкции: [**INSTRUCTION-GET-TOKEN-RU.md**](./INSTRUCTION-GET-TOKEN-RU.md) (ссылка с `response_type=token` и вашим `client_id`).
2. Скопируйте **`access_token`** из адреса после `#` (не путайте с «кодом подтверждения» из другого потока).
3. В OpenClaw вставьте токен в конфиг плагина **`yandex-metrika-assistant`** → поле **`oauthToken`**, либо задайте переменную **`YANDEX_METRIKA_OAUTH_TOKEN`** (если ваш хост так настроен).
4. Опционально задайте **`defaultCounterId`**, чтобы агент не спрашивал номер счётчика каждый раз.

---

## После добавления ключа — с чего начать

Напишите агенту одну из фраз (или свою):

1. **«Покажи список моих счётчиков Метрики»** — проверка, что токен и права работают.  
2. **«Визиты по дням за последние 7 дней для счётчика …»** — базовый отчёт по датам.  
3. **«Откуда трафик за месяц?»** / **«Сводка по источникам»** — источники и каналы.  
4. **«Топ страниц по просмотрам»** — какие URL набирают больше всего просмотров.  
5. **«Сколько было достижений цели …»** — конверсии (нужен id или название цели).  

Больше идей: [`10-user-intents-matrix.md`](./10-user-intents-matrix.md), примеры команд: [`EXAMPLES.md`](./EXAMPLES.md).

---

## Краткий чеклист

- [ ] Плагин/навык установлен и включён в OpenClaw  
- [ ] Приложение OAuth создано, Redirect URI верный  
- [ ] Нужные **галочки Метрики** в приложении включены  
- [ ] Токен получен и сохранён в **секретах** (не в чат)  
- [ ] Написано первое тестовое сообщение агенту из списка выше  

Удачи. При затыках — [**@maya_pro**](https://t.me/maya_pro).


path: docs/INSTRUCTION-GET-TOKEN-RU.md
content: # Как получить ключ доступа к API Яндекс.Метрики

**Поддержка и вопросы по установке:** канал [**@maya_pro в Telegram**](https://t.me/maya_pro). Токены и пароли в открытый чат не отправляйте.

Перед первым получением токена удобно пройти полную установку: **[INSTALL-FOR-HUMANS-RU.md](./INSTALL-FOR-HUMANS-RU.md)**.

---

Для запросов к API Метрики нужен не отдельный «API-ключ из кабинета Метрики», а **OAuth-токен** Яндекса. Его выдаёт сервис [Яндекс OAuth](https://oauth.yandex.ru/) после входа в аккаунт и согласия прав.

Ниже — способ, который использует **неявный поток** (`response_type=token`): после входа токен появляется **в адресной строке браузера** (во фрагменте URL после символа `#`).

---

## Что понадобится заранее

1. Аккаунт на Яндексе с доступом к нужным счётчикам Метрики.
2. **Приложение** в [Яндекс OAuth](https://oauth.yandex.ru/). Ниже — что выбрать при создании и в настройках.

### Тип приложения

- Выберите вариант вроде **«Для доступа к API или отладки»** (название в интерфейсе может слегка отличаться).

### Доступ к данным: отметьте нужные пункты по Метрике

В блоке прав доступа к **Яндекс.Метрике** включите те возможности, которые вам нужны. Для полного набора (отчёты + управление счётчиками + загрузки) отметьте **все** перечисленные ниже — формулировки приведены как в кабинете OAuth (если у вас текст чуть другой, ориентируйтесь по смыслу):

- [ ] **Получение статистики, чтение параметров своих и доверенных счётчиков** — соответствует `metrika:read`.
- [ ] **Создание счётчиков, изменение параметров своих и доверенных счётчиков** — соответствует `metrika:write`.
- [ ] **Загрузка расходов** — `metrika:expenses` (по документации Метрики не обязателен в ссылке, если уже есть `metrika:write`, но галочка в приложении нужна, если вы грузите расходы).
- [ ] **Загрузка параметров пользователей** — `metrika:user_params` (аналогично: для загрузки параметров галочка должна быть в приложении).
- [ ] **Загрузка офлайн данных (данные из CRM, офлайн конверсии, звонки)** — `metrika:offline_data` (нужна для CRM/офлайн-конверсий/звонков).

Если какой-то из типов доступа вам **не нужен**, снимите соответствующую галочку и **уберите** лишнее из параметра `scope` в ссылке авторизации (см. таблицу ниже), иначе возможна ошибка `invalid_scope`.

### Платформа и Redirect URI

- Укажите платформу **«Веб-сервисы»** (или аналог), добавьте **Redirect URI**:

  `https://oauth.yandex.ru/verification_code`

  Он должен быть **точно таким же** в настройках приложения и в ссылке из шага 1 ниже.

### После сохранения приложения

- Сохраните приложение и скопируйте **Client ID** (идентификатор приложения) из карточки приложения — он понадобится в ссылке авторизации.

---

## Права Метрики в параметре `scope`

В ссылке авторизации права перечисляются в `scope` через **пробел** (в URL пробел кодируют как `%20`). В кабинете [oauth.yandex.ru](https://oauth.yandex.ru/) должны быть включены те же возможности, что вы перечисляете в `scope`, иначе возможна ошибка `invalid_scope`.

| Возможность | Значение в `scope` |
|-------------|-------------------|
| Получение статистики, чтение параметров своих и доверенных счётчиков | `metrika:read` |
| Создание счётчиков, изменение параметров своих и доверенных счётчиков | `metrika:write` |
| Загрузка расходов | `metrika:expenses` (не обязателен, если есть `metrika:write`) |
| Загрузка параметров пользователей | `metrika:user_params` (не обязателен, если есть `metrika:write`) |
| Загрузка офлайн данных (данные из CRM, офлайн конверсии, звонки) | `metrika:offline_data` (не обязателен, если есть `metrika:write`) |

Если в приложении отмечены все нужные галочки Метрики, часто достаточно запросить **`metrika:read`** и **`metrika:write`** — остальные три scope из таблицы дублируют часть возможностей `metrika:write` и могут не пониматься в ссылке, если не добавлены отдельно в настройках приложения.

---

## Шаг 1. Соберите ссылку для входа

Подставьте **свой** `client_id` вместо `ВАШ_CLIENT_ID`.

Права в примере: чтение и запись Метрики (`metrika:read` и `metrika:write`). Если в приложении не включены какие-то из запрошенных прав, авторизация может завершиться ошибкой `invalid_scope` — тогда уберите лишнее из параметра `scope` или добавьте галочки в настройках приложения.

```
https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID&redirect_uri=https%3A%2F%2Foauth.yandex.ru%2Fverification_code&scope=metrika%3Aread%20metrika%3Awrite
```

**Рабочий пример** (замените на свой Client ID, если отличается):

```
https://oauth.yandex.ru/authorize?response_type=token&client_id=c244cafa27d047dd87dfa6189aa48fc4&redirect_uri=https%3A%2F%2Foauth.yandex.ru%2Fverification_code&scope=metrika%3Aread%20metrika%3Awrite
```

Откройте ссылку **в браузере** (лучше в режиме обычного окна, чтобы было проще скопировать адрес).

---

## Шаг 2. Войдите и разрешите доступ

1. Войдите под тем аккаунтом Яндекса, для которого нужен доступ к Метрике.
2. На экране согласия нажмите разрешение доступа приложению.

---

## Шаг 3. Скопируйте токен из адреса

После успешного входа браузер перенаправит на страницу вида:

`https://oauth.yandex.ru/verification_code#access_token=ДЛИННАЯ_СТРОКА&token_type=bearer&expires_in=...`

1. Посмотрите на **полный адрес** в строке браузера (иногда фрагмент `#...` не виден сразу — нажмите на адресную строку или «Изменить» / полный URL).
2. Найдите в части после `#` параметр **`access_token=`**.
3. Скопируйте значение **от первого символа токена до следующего символа `&`** (без слова `access_token=`).

Это значение и есть **ключ**, который нужно передавать в API Метрики в заголовке:

```http
Authorization: OAuth <скопированный_access_token>
```

Пример для проверки (подставьте свой токен):

```bash
curl -s -H "Authorization: OAuth ВАШ_ТОКЕН" "https://api-metrika.yandex.net/management/v1/counters?per_page=5"
```

При успехе вернётся JSON со списком счётчиков и код ответа **200**.

---

## Срок жизни токена

У токена есть срок действия (в URL обычно есть `expires_in` в секундах). Когда срок истечёт, нужно **снова открыть ссылку из шага 1** и получить новый токен.

Для серверных сценариев без постоянного открытия браузера чаще используют поток с **кодом** (`response_type=code`) и **обмен на токен** с `client_secret`, плюс **refresh_token** — это описано в [документации Яндекс OAuth](https://yandex.ru/dev/id/doc/ru/codes/code-url).

---

## Безопасность

- Не отправляйте токен в чаты, не публикуйте в скриншотах и **не коммитьте** в репозиторий.
- Храните только в защищённом месте: менеджер секретов, переменные окружения на сервере, зашифрованные настройки.
- Если токен утёк — отзовите доступ приложения к аккаунту или перевыпустите токен через повторную авторизацию; при необходимости смените **Client secret** в кабинете OAuth.

---

## Частые ошибки

| Проблема | Что сделать |
|----------|-------------|
| `invalid_scope` | В ссылке запрошены права, которых нет у приложения в [oauth.yandex.ru](https://oauth.yandex.ru/). Упростите `scope` (например, только `metrika%3Aread`) или добавьте галочки в настройках приложения. |
| Нет `#access_token` в адресе | Убедитесь, что в ссылке указано `response_type=token` и разрешён такой тип для вашего приложения. Проверьте, что `redirect_uri` совпадает с настройками. |
| 401 у API Метрики | Токен истёк или скопирован не полностью; заголовок должен быть ровно `Authorization: OAuth ` + токен без кавычек. |

---

## Куда смотреть официально

- OAuth и токены: https://yandex.ru/dev/id/doc/ru/concepts/ya-oauth-intro  
- API Метрики и заголовок `Authorization`: https://yandex.ru/dev/metrika/ru/intro/authorization  
- Хаб Метрики: https://yandex.ru/dev/metrika  


path: docs/OPENCLAW-AGENT.md
content: # Заметки для агента OpenClaw (установка и тест)

## HOOK.md не нужен

В корне репозитория есть **`openclaw.plugin.json`** — это **нативный плагин** OpenClaw с вложенным навыком (`"skills": ["."]` → тот же каталог с **`SKILL.md`**).

- **Hook** — отдельный тип расширения; для этого проекта файл **`HOOK.md` не предусмотрен** и **не обязателен**.
- Если установщик ищет только hook — ставьте артефакт как **skill** (`openclaw skills install …`) **или** как **плагин** (`openclaw plugins install <path>`) и включайте плагин в `plugins.entries`.

## Тест API без «проблем с кавычками» (Windows PowerShell)

`curl.exe` с длинным заголовком `Authorization` в нескольких строках с **обратными кавычками** часто ломается из‑за вложенных `"` или «умных» кавычек из мессенджера.

**Предпочтительно для проверки:** `Invoke-RestMethod` и хештаблица заголовков (токен только из переменной окружения или секрета, **не** вставлять токен в чат в команду целиком).

```powershell
$env:YANDEX_METRIKA_OAUTH_TOKEN = '<ВСТАВИТЬ_ТОЛЬКО_ЛОКАЛЬНО_ИЗ_СЕКРЕТА>'
$h = @{ Authorization = 'OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN }
Invoke-RestMethod -Uri 'https://api-metrika.yandex.net/management/v1/counters?per_page=5' -Headers $h
```

Одинарные кавычки `'...'` вокруг URI снижают риск, что PowerShell что‑то подставит лишнее.

## Однострочный curl (если нужен именно curl)

```powershell
curl.exe -s -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) "https://api-metrika.yandex.net/management/v1/counters?per_page=5"
```

Здесь заголовок собран через **конкатенацию**, без вложенных двойных кавычек вокруг токена.

## Токен

- Не просить пользователя присылать токен в открытый чат; если прислали — **не повторять** токен в ответе и посоветовать **перевыпустить** в [oauth.yandex.ru](https://oauth.yandex.ru/).
- В OpenClaw: `plugins.entries.yandex-metrika-assistant.config.oauthToken` или `skills.entries` / секреты хоста — см. [`SKILL.md`](../SKILL.md).

Больше примеров: [`EXAMPLES.md`](./EXAMPLES.md).


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)