Выгрузки

В продукте есть две выгрузки, и они решают разные задачи. Первая отдаёт результат отчёта — те же строки, что вы видите на экране, чтобы приложить их к письму или досчитать в таблице. Вторая отдаёт события — по строке на событие, чтобы положить их в своё хранилище. Обе синхронные: файл начинает скачиваться в том же запросе, задание в очередь не ставится.

Результат отчёта в CSV

Кнопка «Скачать CSV» стоит в тулбаре экранов, где есть результат:

Экран	Что попадает в файл
Анализ → Воронки	шаги, значения, конверсия к предыдущему и к первому шагу, среднее время до шага
Анализ → Удержание	когорты, размер когорты, удержание по периодам
Анализ → Аналитика, вкладка «Тренды»	серии, периоды, значения, интервал
Анализ → Аналитика, вкладка «Расширенный анализ»	режим расчёта, пометка об оценочном характере, метрики режима
Анализ → Пути пользователей	маршруты, узлы, доли и отвалы
Данные и сбор → События	события с текущими фильтрами списка

Формат файла:

• UTF-8 с меткой порядка байтов — Excel открывает без «Мастера импорта текста».
• Разделитель строк CRLF, экранирование по RFC 4180.
• Первые три колонки каждой строки — версия схемы, локаль и часовой пояс проекта. Они повторяются в каждой строке намеренно: файл остаётся самодостаточным, если из него вырезали фрагмент.
• Текстовая ячейка, начинающаяся с =, +, - или @, получает ведущий апостроф, чтобы табличный редактор не выполнил её как формулу.

Схема CSV расширяется только вправо: новая ревизия дописывает колонки в конец и не меняет смысл и позицию прежних. Парсер, который читает колонки по имени из заголовка, ревизию переживёт; парсер, который читает по фиксированным позициям, — нет.

Границы одной выгрузки — 100 000 строк данных (заголовок не считается) и 30 секунд на весь запрос. Если строк больше, файл не начинает скачиваться: приходит понятный отказ с указанием лимита, а не обрезанный результат.

Выгрузка событий

Экран Данные и сбор → События даёт две кнопки, и они отличаются не только форматом.

	«Скачать CSV»	«Экспорт NDJSON»
Формат	CSV, одна таблица	по одному JSON-объекту на строку
Лимит строк	100 000	1 000 000
Лимит диапазона	нет	31 день
Время на запрос	30 секунд	30 секунд
Роль	любой участник	аналитик и выше
Тариф	на всех тарифах	Growth и Scale

Обе выгрузки берут ровно те фильтры, что есть на экране: имена событий (можно несколько), user_id, anon_id и период. Для NDJSON период обязателен — выбранные в календаре даты превращаются в диапазон по UTC с включённым последним днём.

Строка NDJSON содержит версию схемы, идентификаторы (project_id, event_id, event_name, actor_id, user_id, anon_id, session_id), обе метки времени (event_time, server_time), props как вложенный объект, url, referrer, UTM-метки и производные признаки: device_type, os, browser, country. Сырой IP-адрес и строка user-agent в выгрузке отсутствуют — они не хранятся вовсе.

Кнопка «Экспорт NDJSON» видна на любом тарифе намеренно: клик всегда доходит до серверной проверки прав, и вы получаете честный отказ вместо спрятанного элемента. На тарифе без этой возможности приходит feature_locked.

Как читать поток и не потерять хвост

Выгрузка отдаёт 200 OK и сразу начинает писать тело. Если что-то сломается после первого байта, кода ошибки в теле не будет — статус уже отправлен. Результат сообщается в трейлерах ответа:

Трейлер	Значения
X-PP-Export-Status	ok, error, timeout, canceled
X-PP-Export-Error-Code	код отказа, когда статус не ok

Обрыв транспорта может усечь последнюю строку JSON. Поэтому клиент обязан разбирать каждую строку и требовать трейлер X-PP-Export-Status: ok: только он подтверждает, что поток дошёл целиком. Отсутствие трейлера доказательством успеха не является — считайте такую выгрузку неполной и повторите её.

Ещё две полезные заголовочные подсказки: X-PP-Export-Schema — версия схемы файла, X-PP-Timezone — часовой пояс проекта, в котором посчитаны локальные даты отчёта.

Лимиты частоты

Обе выгрузки делят один бюджет на организацию: 10 запусков в минуту и 2 одновременные выгрузки. Плюс потолок на процесс — 8 одновременных. При превышении приходит 429, а в интерфейсе — сообщение «Слишком много экспортов. Попробуйте позже».

Практический вывод для скриптов: не запускайте выгрузки параллельно. Два последовательных запроса надёжнее восьми одновременных, а третий и четвёртый одновременных всё равно упрутся в лимит.

Что делать с большими объёмами

Продукт сознательно не выдаёт «весь проект одним файлом»: любая выгрузка ограничена по строкам и по времени, чтобы не превратиться в неуправляемую нагрузку на аналитическую базу. Порядок для больших объёмов такой.

1. Режьте по времени. Для NDJSON — окнами до 31 дня, при большом потоке — по неделям или по дням. Ориентир: одно окно должно уложиться в 1 000 000 записей и 30 секунд.
2. Режьте по событиям. Фильтр по имени события можно указать несколько раз, так что тяжёлые технические события можно выгрузить отдельно от бизнесовых или не выгружать совсем.
3. Идите последовательно и сверяйте трейлер каждого окна перед переходом к следующему. Окно с timeout нужно повторить более узким, а не пропустить.
4. Для чтения по страницам используйте список событий с курсором — там работает обычная постраничность продукта, см. постраничность. Курсор привязан к области запроса: меняете фильтры или диапазон — начинаете страницы заново.

Если задача не «слить всё», а «посчитать конкретное», обычно дешевле посчитать в SQL-консоли и выгрузить результат: агрегат почти всегда на порядки меньше сырых событий.

Чего в продукте нет

Асинхронной постановки выгрузки в очередь. Задания «поставить выгрузку и получить ссылку на готовый файл» в ActionPulse не существует — эта возможность числится в тарифном каталоге как ещё не построенная и ни на одном тарифе не включена. Не рассчитывайте на неё в проектировании интеграции.

Рабочие альтернативы, в порядке предпочтения:

• Поток NDJSON окнами до 31 дня — прямой аналог полной выгрузки, просто разбитый на части и без промежуточного файла на нашей стороне.
• Список событий с курсором — когда нужен не файл, а инкрементальное чтение в свой приёмник.
• Агрегат из SQL-консоли — когда достаточно посчитанного результата. Кнопка «Экспорт CSV» на панели результата собирает файл прямо в браузере из уже полученных строк, ничего дополнительно не запрашивая; ограничение — выбранный лимит строк консоли, не больше 10 000.

Ссылки, которая открывает отчёт или панель без входа в кабинет, в продукте тоже нет, поэтому выгрузка остаётся основным способом отдать числа наружу — как это делать аккуратно, см. публикация отчётов.

Частые ошибки

Что видно	Причина	Что сделать
«Экспорт превышает лимит … строк»	результат не проходит по лимиту	сузьте период или фильтры; для событий возьмите окно короче
«Экспорт не успел завершиться»	не уложились в 30 секунд	сузьте диапазон; для NDJSON — окна по дням
«Экспорт NDJSON недоступен на текущем тарифе»	тариф без этой возможности или идёт триал	используйте CSV-выгрузку списка событий с того же экрана
«Недостаточно прав для экспорта»	у роли нет права на выгрузку событий	нужна роль аналитика или выше
«Слишком много экспортов»	10 запусков в минуту или 2 одновременные	выстройте выгрузки последовательно
Файл скачался, но данных меньше ожидаемого	диапазон задан по времени приёма	проверьте, не история ли это, загруженная импортом
Excel показывает вместо текста иероглифы	файл открыли не как UTF-8	не переоткрывайте файл вручную: выгрузка уже содержит метку порядка байтов