Link-analytics-API: klikstatistieken ophalen met een API-sleutel

De link-analytics-API van Elido is één endpoint, GET /v1/workspaces/{workspace_id}/analytics/{report} op https://api.elido.app, geauthenticeerd met een API-sleutel van een werkruimte. Het levert 15 rapporten: kliktijdreeks, een samenvatting van betrokkenheid, toplinks, een met een cursor gepagineerde feed van recente klikken en uitsplitsingen naar land, referrer, apparaat, browser, host en bestemming. Datums staan standaard op de afgelopen 30 dagen, link_id beperkt elk rapport tot één korte link, en de CSV-export, funnels, cohorten en LTV blijven in het dashboard.

Dat is het hele antwoord als je alleen de URL nodig had. De rest van deze gids is wat ik wou dat elke pagina over een klikanalytics-API meteen vertelde: de exacte parameters, de JSON die je terugkrijgt, waar het datumbereik stilletjes anders werkt dan je zou denken en een script van 30 regels dat elke ochtend de cijfers van gisteren in Slack post.

De meeste mensen die klikdata ophalen, sluiten een lus die begint met campagnetagging, dus als je links nog geen consistente UTM's dragen, los dat dan eerst op met UTM-tracking van begin tot eind. Schone invoer maakt de statistieken het ophalen waard.

Wat de link-analytics-API teruggeeft

Elk rapport leeft onder hetzelfde pad en de rapportnaam is het laatste segment. Namen met een schuine streep (links/top, clicks/recent, breakdown/country) gaan ongecodeerd mee. Vraag je iets buiten de toegestane lijst, dan krijg je een 404 met unknown analytics report.

Let op de laatste rij. De rapporten voor regio en stad verpakken hun rijen in points, niet in items, omdat elke rij een land plus een regio of stad bevat in plaats van één sleutel. Ik heb een generieke parser daar precies één keer over zien struikelen. Eén keer is genoeg.

Hetzelfde oppervlak ligt onder de API en SDK's, de analyticstool van de MCP-server en de bewerking Get Analytics in het n8n-knooppunt, dus wat je hier leert, geldt ook daar.

Authenticeren met een API-sleutel van een werkruimte

API-sleutels beginnen met elido_ en horen bij precies één werkruimte. Stuur de sleutel mee als bearer-token:

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

De router controleert twee dingen voordat een query draait: dat de sleutel bij werkruimte 4821 hoort en dat hij analytics.view heeft. Elke ingebouwde rol heeft dat recht, Viewer inbegrepen. Maak dus een Viewer-sleutel voor rapportagejobs. Een rapportage-cron hoort geen links te kunnen verwijderen, en een Viewer-sleutel kan dat niet. Een sleutel zonder toegang krijgt een 403.

link_id verbreedt de toegang ook niet. De werkruimte-ID in het pad is degene die is gecontroleerd, dus een link-ID geleend uit de werkruimte van een ander komt met nul rijen overeen en geeft een lege lijst terug. Dat is de juiste manier om te falen: saai, en er lekt niets.

Queryparameters voor klikstatistieken: datums, tijdzone, filters

Zes parameters dekken bijna elke aanroep van een API voor statistieken van korte links:

• from en to, als YYYY-MM-DD. Laat je ze allebei weg, dan krijg je de 30 dagen tot nu. Zet je alleen to, dan staat from standaard 30 dagen ervoor.
• link_id om elk rapport tot één link te beperken en host om het tot één redirectdomein te beperken, handig wanneer een werkruimte meerdere gebrandmerkte domeinen draait.
• interval voor timeseries, hour of day (de standaard). Al het andere laat het verzoek falen.
• limit voor uitsplitsingen en toplijsten, 1 tot 200, standaard 50. links/top is de uitzondering: hij geeft 10 terug tenzij je om meer vraagt.

Dit is het detail waarover je struikelt. Beide datums worden gelezen als middernacht UTC, en het venster omvat from maar stopt vóór to. Voor heel 21 september stuur je from=2026-09-21&to=2026-09-22. Stuur je to=2026-09-21, dan krijg je helemaal niets van die dag.

Tijdzone is de andere. Geef tz mee als IANA-tijdzonenaam of zet een header X-User-TZ, en timeseries snijdt zijn uur- of dagbuckets op lokale tijd. Alleen de buckets verschuiven. Het venster from/to blijft UTC, dus een "gisteren" in Berlijn vraagt een iets breder venster, wat het script hieronder afhandelt. Een typefout als Europe/Berln geeft een 400 met unknown IANA timezone, en dat is beter dan een stilzwijgend foute grafiek.

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"

Antwoordvormen waartegen je kunt programmeren

Een tijdreekspunt bevat ts, een RFC 3339-tijdstempel voor het begin van de bucket, en count. Buckets met nul klikken ontbreken eenvoudigweg, dus vul de gaten zelf aan voordat je een grafiek maakt, anders verdwijnt een rustige zondag van de x-as.

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

Uitsplitsingen geven {"items": [{"key": "DE", "count": 1204}, ...]} terug, gesorteerd op aantal. De samenvatting is een plat object:

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

Twee definities doen ertoe. Unieke bezoekers worden geteld op afzonderlijk IP-adres binnen het venster, dus een kantoor achter één verbinding telt één keer. En bounce_rate is een breuk, geen percentage: het aandeel unieke bezoekers dat binnen het venster maar één keer klikte. Het zegt niets over wat er op je landingspagina gebeurde, en daarom komen deze cijfers nooit overeen met GA4-sessies (het artikel klikken versus GA4-sessies loopt het verschil door). Elk cijfer is op bots gefilterd voordat het je bereikt, dezelfde aantallen die je ziet in de linkanalytics van Elido.

Recente klikken pagineren met een cursor

clicks/recent is het rapport van de linktracking-API dat afzonderlijke klikken teruggeeft, nieuwste eerst. Elke rij heeft ts, link_id, slug, host, referer, country_code, device, browser, destination, user_agent en ip. De paginagrootte is 1 tot 500, standaard 100.

Komt een pagina vol terug, dan bevat het antwoord een next_cursor. Geef die mee als ?cursor= voor de volgende, oudere pagina; null betekent dat je het einde van het venster hebt bereikt.

De cursor wijst naar het tijdstempel en de link-ID van de laatste rij. Twee klikken op dezelfde link in dezelfde milliseconde kunnen op een paginagrens gelijk eindigen, en in het slechtste geval krijg je één dubbele rij, nooit een overgeslagen. Ontdubbel op de volledige rij wanneer je ze opslaat. Zeldzaam, maar een insert van tien regels verslaat het uitleggen van een off-by-one aan de financiële afdeling.

Die rijen bevatten IP-adressen en user-agents, dus het zijn persoonsgegevens. Kopieer je ze naar een datawarehouse, houd dat dan in de EU en stel een bewaartermijn in; de gids over dataopslag in de EU voor marketingteams behandelt de redenering. Voor de meeste rapporten heb je helemaal geen ruwe rijen nodig, en een dagelijks aggregaat is vriendelijker voor iedereen.

Een script voor een dagelijks klikrapport in Slack of een blad

Dit is de klus die de meeste mensen echt willen: elke ochtend de klikken van gisteren en de top vijf links in een kanaal posten. Het gebruikt alleen de standaardbibliotheek van Python en een inkomende 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"}))

Draai het vanuit cron om 07:00 lokale tijd. De uurtruc maakt van het totaal een echte Berlijnse dag in plaats van een UTC-dag; links/top heeft geen tz, dus de ranglijst blijft op de UTC-dag, en het bericht zegt dat ook.

Liever een blad? Dezelfde twee aanroepen werken vanuit Google Apps Script met UrlFetchApp en een dagelijkse trigger, die één rij per dag toevoegt. Dat is ook de goedkoopste weg naar een Looker Studio-dashboard.

Plak je elke maandag nog cijfers uit screenshots, geef dan een Viewer-sleutel aan een script en heb je ochtenden terug.

Wat alleen in het dashboard blijft

Het oppervlak van API-sleutels is alleen-lezen en bewust smaller dan het dashboard. Deze zijn niet bereikbaar met een sleutel:

• De CSV-export van klikken (clicks.csv). De knop Download CSV in het dashboard is de route voor bulkbestanden.
• Funnels, cohorten, het LTV-rapport, de heatmaps voor tijd en geo en de weergave van verkeerskwaliteit.

Als je alleen wilt dat er op schema ergens een bestand landt, doen de geplande e-mailrapporten in het dashboard dat zonder code. Voor een volledige export waarmee je kunt afscheid nemen, zie wat je kunt exporteren uit een account voor korte links en hoe je controleert of het volledig is. En een gecombineerde aanroep "alles voor één link" bestaat nog niet, dus een dashboard per link betekent één verzoek per rapport. De SDK-quickstart behandelt hoe je die parallel draait en terugschakelt wanneer je de rate limits raakt.

De klikanalytics-API pollen versus webhooks voor realtime

De eerlijke versie: vandaag zijn klikdata alleen op te halen. Elido-webhooks pushen link- en domeingebeurtenissen, ondertekend en met nieuwe pogingen, maar een gebeurtenis click.created per klik staat op de roadmap en wordt nog niet verstuurd. Alles wat realtime is rond klikken betekent clicks/recent pollen.

Dat is minder pijnlijk dan het klinkt. Poll elke minuut of twee, stop zodra je een rij bereikt die je al hebt opgeslagen, en de belasting blijft minimaal, want een rustige minuut is één kleine pagina. Wanneer click.created uitkomt, maakt het de handler die een rij verwerkt niet uit of die van een pagina of een push komt. De afwegingen in het algemeen staan in webhooks versus polling voor kliktracking, en als je nog beslist welke van deze cijfers een rapport verdienen, is wat je meet in analytics van korte links de kortere lectuur.

Mijn mening: begin met de dagelijkse samenvatting. Bijna elk team dat me om realtime klikken vraagt, is tevreden met de cijfers van gisteren, geleverd vóór de koffie.

Lees de hoeksteen → UTM-campagnes van begin tot eind volgen

Verwant op de blog

• Quickstart voor de API en SDK's van de URL-verkorter - sleutels, SDK's, rate limits en de aanmaakaanroep.
• n8n-knooppunt voor de URL-verkorter - dezelfde analyticsrapporten binnen een n8n-workflow.
• Webhooks versus polling voor kliktracking - het integratiepatroon kiezen.
• Linkanalytics in Looker Studio - de dagelijkse pull omzetten in een dashboard.
• Elido koppelen aan Claude en Cursor met MCP - klikstatistieken opvragen in gewone taal.