Paginierung

Paginierung teilt eine lange Ergebnisliste der API in Seiten, die Sie nacheinander abrufen. Ein Beispiel: Ihre Website hatte im Oktober 2.450 Sessions von Unternehmen, und mit page_size=1000 liefert /session sie auf drei Seiten mit 1.000, 1.000 und 450 Einträgen.

Die API liefert keinen Cursor und keinen Link zur nächsten Seite, deshalb zählen Sie page selbst hoch.

Ablauf beim BlätternCopy Anchor Link

1. 1Erste Seite abrufenSie fragen mit page=1 an.
2. 2Seitenangaben lesenDer Block pagination nennt die aktuelle Seite und die Zahl der Seiten.
3. 3Nächste Seite abrufenWenn noch eine Seite offen ist, warten Sie etwas länger als eine Sekunde und erhöhen page um 1.
4. 4Ende erkennenWenn current mindestens page_total ist, haben Sie alle Seiten.

Parameter für SeitenCopy Anchor Link

Die Endpunkte /company-sessions, /company, /company_nace, /session und /session_user_data nehmen zwei Parameter an:

• page: die Nummer der Seite, beginnend bei 1, mit 1 als Standard.
• page_size: die Zahl der Einträge pro Seite, höchstens 10.000 und standardmäßig ebenfalls 10.000.

Mit dem Standardwert von 10.000 passt der ganze Zeitraum oft auf eine einzige Seite.

Wenn page oder page_size kleiner als 1 oder page_size größer als 10.000 ist, antwortet die API mit Status 422 und dem Code VALIDATION_ERROR. Mehr dazu unter Fehler.

Seitenangaben in der AntwortCopy Anchor Link

Jede Antwort dieser Endpunkte enthält die Felder pagination und result. Dabei ist pagination eine Liste mit genau einem Eintrag, kein einzelnes Objekt.

Diese Anfrage ruft die zweite von drei Seiten ab:

curl "https://hub.webmetic.de/session?domain=ihre-website.de&from_date=2026-10-01&to_date=2026-10-31&page=2&page_size=1000" \
  -H "Authorization: wmtc_IHR_API_SCHLUESSEL"

Die Antwort, hier gekürzt auf den Block pagination, sieht so aus:

{
  "pagination": [
    {
      "total": 2450,
      "page_total": 3,
      "isFirst": false,
      "current": 2,
      "isLast": false,
      "page_size": 1000
    }
  ]
}

• total: die Zahl der Einträge über alle Seiten.
• page_total: die Zahl der Seiten.
• current: die angefragte Seite.
• isFirst: true auf Seite 1.
• isLast: true, wenn current mindestens page_total ist. Das gilt auch für ein leeres Ergebnis.
• page_size: die Zahl der Einträge pro Seite.

Schleife über alle SeitenCopy Anchor Link

Die Schleife fragt Seite für Seite an, bis current mindestens page_total ist. Eine Prüfung auf isLast hätte dasselbe Ergebnis. Bei einem leeren Ergebnis ist page_total 0, und die Schleife endet schon nach der ersten Anfrage.

Zwischen zwei Seiten wartet die Schleife etwas länger als eine Sekunde, weil die Besuchs-Endpunkte eine Anfrage pro Sekunde je Endpunkt beantworten. Die Einzelheiten stehen unter Anfragelimits.

const rows = [];
let page = 1;
while (true) {
  const params = new URLSearchParams({
    domain: 'ihre-website.de',
    from_date: '2026-10-01',
    to_date: '2026-10-31',
    page: String(page),
    page_size: '1000',
  });
  const res = await fetch(`https://hub.webmetic.de/session?${params}`, {
    headers: { Authorization: 'wmtc_IHR_API_SCHLUESSEL' },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const body = await res.json();
  rows.push(...body.result);
  const info = body.pagination[0]; // pagination is a list with one object
  if (info.current >= info.page_total) break;
  page += 1;
  await new Promise((resolve) => setTimeout(resolve, 1100)); // 1 request per second
}

Geben Sie beim Blättern ein festes to_date an, zum Beispiel 2026-10-31, und nicht now oder einen relativen Wert wie -1 days. Sonst kommen zwischen zwei Anfragen neue Besuche hinzu und verschieben die Einträge.

Reihenfolge der EinträgeCopy Anchor Link

Bei den Besuchs-Endpunkten ist die Reihenfolge der Einträge nicht festgelegt, und ein Eintrag kann beim nächsten Abruf auf einer anderen Seite stehen. Sortieren Sie die Daten deshalb nach dem Abruf selbst.

Wenn Sie alle Einträge vollständig brauchen, rufen Sie sie mit einer großen page_size auf einer Seite ab oder teilen den Abruf in kürzere Zeiträume. Zeiträume und Zeitzonen beschreibt, wie Sie Zeiträume angeben.

Endpunkte im ÜberblickCopy Anchor Link

/intensive-visits, /returning-visits und /new-visits haben keine Seiten und liefern alle passenden Unternehmen auf einmal. Wenn die Antwort zu groß wird, wählen Sie mit from_date und to_date einen kürzeren Zeitraum.

Enrichment-ListenCopy Anchor Link

GET /enrichment/lists und GET /enrichment/lists/{list_id}/rows blättern wie die Besuchs-Endpunkte: page beginnt bei 1, und beide nutzen page_size und denselben Block pagination. Beide liefern die neuesten Einträge zuerst.

• /enrichment/lists: page_size ist standardmäßig 1.000 und höchstens 10.000. Die Listen stehen im Feld lists.
• /enrichment/lists/{list_id}/rows: page_size ist standardmäßig und höchstens 10.000. Die Zeilen stehen im Feld rows neben total. Mit dem Filter status zählt total nur die passenden Zeilen.

Für Enrichment gilt derzeit kein Anfragelimit, deshalb braucht die Schleife dort keine Pause. Der Export /enrichment/lists/{list_id}/export liefert alle Zeilen einer Liste als CSV in einer einzigen Antwort.

KontaktsucheCopy Anchor Link

Die Kontaktsuche POST /contacts/search zählt anders: page steht im JSON-Body und beginnt bei 0. size legt die Treffer pro Seite fest, von 10 bis 25, mit 25 als Standard.

Die Antwort nennt total und page, aber keine Zahl der Seiten und kein isLast. Die letzte Seite haben Sie erreicht, wenn (page + 1) * size mindestens total ist.

Jede Seite ist eine neue Suche, und sie kostet keine Credits, auch nicht auf weiteren Seiten. Erst das Freischalten einer E-Mail-Adresse oder Telefonnummer kostet Credits. Mehr dazu unter Credits in der API.

Nächste SchritteCopy Anchor Link