API аналітики посилань: отримуйте статистику кліків з API-ключем

API аналітики посилань Elido - це одна кінцева точка, GET /v1/workspaces/{workspace_id}/analytics/{report} на https://api.elido.app, з автентифікацією через API-ключ робочого простору. Він віддає 15 звітів: часові ряди кліків, підсумок залучення, найпопулярніші посилання, стрічку останніх кліків зі сторінкуванням курсором, а також розподіли за країною, реферером, пристроєм, браузером, хостом і цільовою адресою. Дати за замовчуванням охоплюють останні 30 днів, link_id звужує будь-який звіт до одного короткого посилання, а CSV-експорт, воронки, когорти й LTV залишаються в панелі керування.

Це вся відповідь, якщо вам була потрібна лише URL-адреса. Решта цього посібника - те, що я хотів би бачити на початку кожної сторінки про API аналітики кліків: точні параметри, JSON, який ви отримаєте у відповідь, місця, де діапазон дат непомітно працює не так, як можна очікувати, і скрипт на 30 рядків, який щоранку надсилає вчорашні числа в Slack.

Більшість людей, які забирають дані кліків, замикають цикл, що починається з розмітки кампаній, тому якщо ваші посилання ще не мають узгоджених UTM, спершу виправте це за допомогою наскрізного відстеження UTM. Чисті вхідні дані роблять статистику вартою отримання.

Що повертає API аналітики посилань

Кожен звіт живе під тим самим шляхом, а назва звіту є останнім сегментом. Назви зі скісною рискою (links/top, clicks/recent, breakdown/country) передаються без кодування. Запитайте будь-що поза дозволеним списком - і отримаєте 404 з unknown analytics report.

Зверніть увагу на останній рядок. Звіти за регіонами й містами обгортають рядки в points, а не в items, бо кожен рядок містить країну плюс регіон або місто замість одного ключа. Я рівно один раз бачив, як універсальний парсер на цьому спіткнувся. Одного разу достатньо.

Той самий інтерфейс стоїть за API та SDK, аналітичним інструментом MCP-сервера й операцією Get Analytics у вузлі n8n, тож усе, що ви тут дізнаєтеся, переноситься й туди.

Автентифікація API-ключем робочого простору

API-ключі починаються з elido_ і належать рівно одному робочому простору. Надсилайте ключ як bearer-токен:

curl -s "https://api.elido.app/v1/workspaces/4821/analytics/summary" \
  -H "Authorization: Bearer $ELIDO_API_KEY"

Перед запуском будь-якого запиту маршрутизатор перевіряє дві речі: що ключ належить робочому простору 4821 і що він має analytics.view. Кожна вбудована роль має цей дозвіл, включно з Viewer. Тож для завдань звітності створіть ключ Viewer. Звітному cron не потрібно вміти видаляти посилання, а ключ Viewer цього не може. Ключ без доступу отримує 403.

link_id теж не розширює доступ. Перевіряється саме ID робочого простору в шляху, тому ID посилання, позичений з чужого робочого простору, збігається з нулем рядків і повертає порожній список. Це правильний збій: нудний, і нічого не витікає.

Параметри запиту для статистики кліків: дати, часовий пояс, фільтри

Шість параметрів покривають майже кожен виклик API статистики коротких посилань, який вам знадобиться:

• from і to, у форматі YYYY-MM-DD. Не передавайте обидва - і отримаєте 30 днів до поточного моменту. Якщо задати лише to, from за замовчуванням буде за 30 днів до нього.
• link_id, щоб обмежити будь-який звіт одним посиланням, і host, щоб обмежити одним доменом переадресації, що зручно, коли робочий простір веде кілька брендованих доменів.
• interval для timeseries, або hour, або day (за замовчуванням). Будь-що інше зламає запит.
• limit для розподілів і списків лідерів, від 1 до 200, за замовчуванням 50. links/top - виняток: він повертає 10, якщо не попросити більше.

Ось деталь, яка кусається. Обидві дати читаються як північ UTC, а вікно включає from, але зупиняється перед to. Для всього 21 вересня надішліть from=2026-09-21&to=2026-09-22. Надішліть to=2026-09-21 - і не отримаєте нічого з цього дня.

Часовий пояс - ще одна така деталь. Передайте tz як назву часового поясу IANA або встановіть заголовок X-User-TZ, і timeseries наріже погодинні чи денні інтервали за місцевим часом. Зміщуються лише інтервали. Вікно from/to усе ще UTC, тому берлінське "вчора" потребує трохи ширшого вікна, з чим скрипт нижче впорається. Помилка на кшталт Europe/Berln повертає 400 з unknown IANA timezone, і це краще, ніж тихо неправильний графік.

curl -s -G "https://api.elido.app/v1/workspaces/4821/analytics/timeseries" \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-22" \
  --data-urlencode "interval=day" \
  --data-urlencode "tz=Europe/Berlin" \
  --data-urlencode "link_id=918273"

Форми відповідей, на які можна спиратися в коді

Точка часового ряду містить ts, мітку часу RFC 3339 для початку інтервалу, і count. Інтервали з нулем кліків просто відсутні, тож заповнюйте прогалини самостійно перед побудовою графіка, інакше тиха неділя зникне з осі x.

{
  "items": [
    { "ts": "2026-09-19T00:00:00Z", "count": 412 },
    { "ts": "2026-09-21T00:00:00Z", "count": 388 }
  ]
}

Розподіли повертають {"items": [{"key": "DE", "count": 1204}, ...]}, відсортовані за кількістю. Підсумок - це плоский об'єкт:

{
  "total_clicks": 5310,
  "unique_visitors": 3987,
  "returning_visitors": 611,
  "avg_clicks_per_visitor": 1.33,
  "bounce_rate": 0.85
}

Важливі два визначення. Унікальні відвідувачі рахуються за різними IP-адресами у вікні, тож офіс за одним підключенням рахується один раз. А bounce_rate - це частка, не відсоток: частка унікальних відвідувачів, які клікнули лише один раз у вікні. Це нічого не говорить про те, що сталося на вашій цільовій сторінці, саме тому ці числа ніколи не збігаються із сесіями GA4 (матеріал про кліки проти сесій GA4 пояснює цю різницю). Кожне число проходить фільтр ботів до того, як потрапить до вас, це ті самі підрахунки, які ви бачите в аналітиці посилань Elido.

Сторінкування останніх кліків курсором

clicks/recent - це звіт API відстеження посилань, який повертає окремі кліки, від найновіших до старіших. Кожен рядок має ts, link_id, slug, host, referer, country_code, device, browser, destination, user_agent і ip. Розмір сторінки - від 1 до 500, за замовчуванням 100.

Коли сторінка повертається повною, відповідь містить next_cursor. Передайте його як ?cursor=, щоб отримати наступну, старішу сторінку; null означає, що ви дійшли до кінця вікна.

Курсор вказує на мітку часу й ID посилання останнього рядка. Два кліки за одним посиланням в одну й ту саму мілісекунду можуть збігтися на межі сторінки, і найгірший випадок - один дубльований рядок, але не пропущений. Під час збереження видаляйте дублікати за повним рядком. Рідкість, але вставка на десять рядків краща за пояснення фінансистам помилки на одиницю.

Ці рядки містять IP-адреси й агенти користувача, тож це персональні дані. Якщо копіюєте їх у сховище даних, тримайте його в ЄС і задайте строк зберігання; посібник з резидентності даних у ЄС для маркетингових команд пояснює причини. Для більшості звітів сирі рядки взагалі не потрібні, а щоденний агрегат людяніший для всіх.

Скрипт щоденного звіту про кліки для Slack або таблиці

Ось завдання, якого насправді хоче більшість людей: щоранку надсилати в канал вчорашні кліки й п'ять найпопулярніших посилань. Воно використовує лише стандартну бібліотеку Python і вхідний Slack webhook.

import datetime as dt, json, os, urllib.parse, urllib.request
from zoneinfo import ZoneInfo

BASE = "https://api.elido.app/v1/workspaces/{ws}/analytics/{report}"
WS, KEY = os.environ["ELIDO_WORKSPACE_ID"], os.environ["ELIDO_API_KEY"]
TZ = ZoneInfo("Europe/Berlin")

def report(name, **params):
    url = BASE.format(ws=WS, report=name) + "?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.load(r)

day = dt.datetime.now(TZ).date() - dt.timedelta(days=1)
# UTC window one day wider on each side, then keep only local hours of `day`
window = {"from": day - dt.timedelta(days=1), "to": day + dt.timedelta(days=2)}
hours = report("timeseries", interval="hour", tz="Europe/Berlin", **window)["items"]
total = sum(p["count"] for p in hours
            if dt.datetime.fromisoformat(p["ts"]).astimezone(TZ).date() == day)

top = report("links/top", limit=5, **{"from": day, "to": day + dt.timedelta(days=1)})
lines = [f"• {l['slug']}: {l['count']}" for l in top["items"]]
text = f"Clicks on {day} (Berlin): {total}\nTop links (UTC day):\n" + "\n".join(lines)

body = json.dumps({"text": text}).encode()
urllib.request.urlopen(urllib.request.Request(
    os.environ["SLACK_WEBHOOK_URL"], data=body,
    headers={"Content-Type": "application/json"}))

Запускайте його з cron о 07:00 за місцевим часом. Погодинний прийом - це те, що робить підсумок справжнім берлінським днем, а не UTC-днем; links/top не має tz, тому його рейтинг залишається в межах UTC-дня, і повідомлення прямо про це каже.

Хочете таблицю? Ті самі два виклики працюють із Google Apps Script через UrlFetchApp і щоденний тригер, додаючи один рядок на день. Це також найдешевший шлях до панелі Looker Studio.

Якщо ви досі щопонеділка переносите числа зі скриншотів вручну, дайте скрипту ключ Viewer і поверніть собі ранки.

Що залишається лише в панелі керування

Доступ через API-ключ працює лише на читання й навмисно вужча за панель керування. Ось до чого ключем не дістатися:

• CSV-експорт кліків (clicks.csv). Для масових файлів шляхом є кнопка завантаження CSV у панелі керування.
• Воронки, когорти, звіт LTV, теплові карти часу й географії, а також перегляд якості трафіку.

Якщо вам достатньо, щоб файл за розкладом потрапляв кудись, заплановані звіти електронною поштою в панелі керування роблять це без коду. Для повного вивантаження під час закриття акаунта подивіться, що можна експортувати з акаунта коротких посилань і як перевірити повноту. А комбінованого виклику "усе для одного посилання" ще не існує, тому панель для окремого посилання означає один запит на кожен звіт. Швидкий старт SDK пояснює, як запускати їх паралельно й робити паузи зі зростаючим інтервалом, коли впираєтеся в обмеження частоти.

Опитування API аналітики кліків проти webhooks для реального часу

Чесна версія: сьогодні дані кліків доступні лише через отримання за запитом. Elido webhooks надсилають події посилань і доменів, з підписом і повторними спробами, але подія click.created для кожного кліку є в планах і ще не надсилається. Усе, що стосується кліків у реальному часі, означає опитування clicks/recent.

Це менш болісно, ніж здається. Опитуйте щохвилини або кожні дві хвилини, зупиняйтеся, щойно доходите до рядка, який уже зберегли, і навантаження лишається крихітним, бо тиха хвилина - це одна мала сторінка. Коли click.created вийде, обробнику рядка буде байдуже, чи прийшов він зі сторінки, чи з надісланої події. Загальні компроміси розкладені в матеріалі webhooks проти опитування для відстеження кліків, а якщо ви вирішуєте, які з цих чисел узагалі заслуговують на звіт, що вимірювати в аналітиці коротких посилань читається швидше.

Моя думка: почніть зі щоденного підсумку. Майже кожна команда, яка просить мене про кліки в реальному часі, щаслива отримувати вчорашні числа до кави.

Читайте основний матеріал → Як відстежувати UTM-кампанії наскрізно

Також у блозі

• Швидкий старт API та SDK скорочувача URL - ключі, SDK, обмеження частоти й виклик створення.
• Вузол n8n для скорочення URL - ті самі аналітичні звіти всередині сценарію n8n.
• Webhooks проти опитування для відстеження кліків - вибір інтеграційного підходу.
• Аналітика посилань у Looker Studio - перетворення щоденного збору за запитом на панель.
• Підключіть Elido до Claude і Cursor через MCP - запитуйте статистику кліків звичайною мовою.