Read API: обзор

Read API отдаёт портфель, аудиторию, retention, realtime, свои события, профили и здоровье интеграции в JSON. Это те же эндпоинты, которыми пользуется дашборд, поэтому цифры совпадают с экранами до последней единицы. Полный список параметров и схем — в разделе API reference.

Адрес и ключСкопировать ссылку на раздел

Базовый адрес — API вашей установки; в примерах стоит условный https://api.analytics.example.com. Ключ sk_… создаётся в «Настройки → API-ключи» и показывается один раз: сервер хранит только хеш и префикс. Ключ передаётся в заголовке:

export AM_SK="sk_…"
curl -sS https://api.analytics.example.com/v1/apps -H "Authorization: Bearer $AM_SK"

Ключ в query string не принимается. Write-ключ pk_… для Read API не подходит.

Отозванный ключ перестаёт работать сразу.

Общие параметры отчётовСкопировать ссылку на раздел

Пример — сводка аудитории за неделю для iOS-версий 3.4.0 и 3.5.0:

curl -sS -G "https://api.analytics.example.com/v1/apps/$APP_ID/audience/summary" \
  -H "Authorization: Bearer $AM_SK" \
  --data-urlencode "from=2026-10-06" \
  --data-urlencode "to=2026-10-12" \
  --data-urlencode "platform=ios" \
  --data-urlencode "app_version=3.4.0" \
  --data-urlencode "app_version=3.5.0"

{
  "from": "2026-10-06",
  "to": "2026-10-12",
  "active": 41230,
  "new": 8120,
  "sessions": 201554,
  "avg_duration_ms": 214500,
  "median_duration_ms": 98000,
  "compare": {
    "from": "2026-09-29",
    "to": "2026-10-05",
    "active": 40102,
    "new": 7998,
    "sessions": 195020,
    "avg_duration_ms": 209870,
    "median_duration_ms": 96500,
    "delta_pct": { "active": 2.81, "new": 1.53, "sessions": 3.35, "avg_duration_ms": 2.21, "median_duration_ms": 1.55 }
  }
}

Доли (retention, share) — числа от 0 до 1, delta_pct — проценты, null при нулевой базе. Время — UTC, кроме начала корзин рядов (ts, minute): они со смещением часового пояса приложения, чтобы граница суток совпадала с отчётом.

ЭндпоинтыСкопировать ссылку на раздел

Сессии в профиле листаются курсором: sessions_limit (до 500) и before — значение next_before из предыдущего ответа. Остальные списки отдаются целиком.

Свои событияСкопировать ссылку на раздел

Операции событий работают со своими событиями приложения. Системные события (session_start, session_end) в них не входят: запрос с таким именем отвечает 404 event_not_found, а событие без вхождений за период — 200 с нулями.

• listEvents отдаёт имена, у которых есть события за период, по убыванию числа событий, затем по имени, не больше 500 имён; truncated равен true, если их было больше. prev_events и prev_people есть только при compare=previous_period.
• getEventReport принимает granularity (hour, day, week, month), как ряд аудитории. events_per_person округляется до двух знаков и равен 0, если событие никто не совершал.
• getEventBreakdown требует property — ключ по шаблону ^[a-z][a-z0-9_]{0,63}$ — и принимает limit от 1 до 100 (по умолчанию 20). Сначала идут топ-значения; other суммирует события остальных значений и считает их людей без повторов, а missing описывает события без свойства.
• listProfileEvents листается курсором, как сессии профиля: limit (от 1 до 200, по умолчанию 50) и before — значение next_before предыдущей страницы.

curl -sS -G "https://api.analytics.example.com/v1/apps/$APP_ID/events/purchase/breakdown" \
  -H "Authorization: Bearer $AM_SK" \
  --data-urlencode "from=2026-10-06" \
  --data-urlencode "to=2026-10-12" \
  --data-urlencode "property=plan"

Ошибки и лимитыСкопировать ссылку на раздел

Ошибки приходят в конверте error с полями code, message и request_id, как в ingest (см. Ошибки и повторы).

В дашборде у каждого отчёта аудитории есть кнопка «Скопировать как запрос к Read API» — она кладёт в буфер готовую команду curl с текущим периодом и фильтрами.