# Paginierung (https://webmetic.de/docs/api/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ättern [#ablauf-beim-blättern]

1. **Erste Seite abrufen**: Sie fragen mit `page=1` an.
2. **Seitenangaben lesen**: Der Block `pagination` nennt die aktuelle Seite und die Zahl der Seiten.
3. **Nächste Seite abrufen**: Wenn noch eine Seite offen ist, warten Sie etwas länger als eine Sekunde und erhöhen `page` um 1.
4. **Ende erkennen**: Wenn `current` mindestens `page_total` ist, haben Sie alle Seiten.

## Parameter für Seiten [#parameter-für-seiten]

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](https://webmetic.de/docs/api/fehler).

## Seitenangaben in der Antwort [#seitenangaben-in-der-antwort]

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:

```bash
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:

```json
{
  "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 Seiten [#schleife-über-alle-seiten]

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](https://webmetic.de/docs/api/anfragelimits).

```js tab="JavaScript" tab-group="lang"
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
}
```

```python tab="Python" tab-group="lang"
import time
import requests

params = {"domain": "ihre-website.de", "from_date": "2026-10-01", "to_date": "2026-10-31",
          "page": 1, "page_size": 1000}
rows = []
while True:
    r = requests.get("https://hub.webmetic.de/session",
                     headers={"Authorization": "wmtc_IHR_API_SCHLUESSEL"}, params=params)
    r.raise_for_status()
    body = r.json()
    rows += body["result"]
    info = body["pagination"][0]  # pagination is a list with one object
    if info["current"] >= info["page_total"]:
        break
    params["page"] += 1
    time.sleep(1.1)  # 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äge [#reihenfolge-der-einträge]

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](https://webmetic.de/docs/api/zeitraeume-und-zeitzonen) beschreibt, wie Sie Zeiträume angeben.

## Endpunkte im Überblick [#endpunkte-im-überblick]

| Endpunkt | Ein Eintrag | Seiten |
| --- | --- | --- |
| `/company-sessions` | Ein Unternehmen mit seinen Sessions im Zeitraum | `page` ab 1 |
| `/company` | Ein Unternehmen | `page` ab 1 |
| `/company_nace` | Ein NACE-Code eines Unternehmens | `page` ab 1 |
| `/session` | Eine Session | `page` ab 1 |
| `/session_user_data` | Ein Seitenaufruf | `page` ab 1 |
| `/intensive-visits`, `/returning-visits`, `/new-visits` | Ein Unternehmen | Alles in einer Antwort |
| `/enrichment/lists` | Eine Liste | `page` ab 1 |
| `/enrichment/lists/{list_id}/rows` | Eine Zeile der Liste | `page` ab 1 |
| `/enrichment/lists/{list_id}/export` | Eine Zeile der CSV-Datei | Alles in einer Antwort |
| `/contacts/search` | Ein Ansprechpartner | `page` ab 0 |
| `/webhooks` | Ein Webhook-Endpunkt | Alles in einer Antwort |

`/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-Listen [#enrichment-listen]

`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.

## Kontaktsuche [#kontaktsuche]

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](https://webmetic.de/docs/api/credits).

## Nächste Schritte [#nächste-schritte]

- [Zeiträume und Zeitzonen](https://webmetic.de/docs/api/zeitraeume-und-zeitzonen): Den Zeitraum mit `from_date` und `to_date` genau festlegen.
- [Anfragelimits](https://webmetic.de/docs/api/anfragelimits): Wie viele Anfragen die API pro Sekunde beantwortet.
- [Fehler](https://webmetic.de/docs/api/fehler): Statuscodes und Fehlercodes der API lesen.