# Session (https://webmetic.de/docs/api/datenmodell/session)

Ein Beispiel: Jemand von Bergquell Mineralbrunnen gelangt morgens über einen Link auf LinkedIn auf Ihre Website und liest die Preisseite, eine Produktseite und die Kontaktseite. Das ist eine Session mit drei Seitenaufrufen.

Wenn dieselbe Person am Nachmittag weiterliest, beginnt eine zweite Session. Auf den Produktseiten dieser Dokumentation heißt die Session Besuch.

## Beginn einer Session [#beginn-einer-session]

Webmetic beginnt eine neue Session in diesen Fällen:

- Ein Besucher ruft an diesem Tag zum ersten Mal eine Seite auf.
- Seit seinem letzten Seitenaufruf sind mehr als 30 Minuten vergangen.
- Ein neuer Tag beginnt, gerechnet in UTC. In Deutschland ist das um 1 Uhr im Winter und um 2 Uhr im Sommer.
- Die Adresse der Seite trägt Kampagnenparameter wie `utm_source` oder eine Klick-ID wie `gclid`, und Quelle oder Medium sind anders als beim vorigen Seitenaufruf.

Für die Kampagnenregel zählen ein direkter Aufruf und ein Link von Ihrer eigenen Website nicht als Wechsel. Nach 30 Minuten oder an einem neuen Tag beginnt aber auch ein direkter Aufruf eine neue Session.

Signale beim Verlassen einer Seite, etwa zur Scrolltiefe, zählen nicht als Seitenaufruf.

Eine Session gehört zu genau einem Besucher, einer Website und einem Webmetic-Konto. Subdomains wie `shop.ihre-website.de` zählen zur selben Website wie `ihre-website.de`. Keine Session reicht über Mitternacht UTC hinaus.

Die API liefert nur Sessions, die Webmetic einem Unternehmen zugeordnet hat. Es fehlen außerdem Besuche nach einem Opt-out und neue Besuche von Unternehmen, die Sie mit der [Domain-Blacklist oder den Organisationstypen](https://webmetic.de/docs/konto/domain-blacklist) ausschließen. Frühere Besuche dieser Unternehmen bleiben in der API.

Eine Session behält ihre `session_id`, wenn später weitere Seitenaufrufe dazukommen. Speichern Sie Sessions deshalb mit der `session_id` als Schlüssel und überschreiben Sie bestehende Einträge.

## Felder [#felder]

| Feld | Typ | Beispiel | Beschreibung |
| --- | --- | --- | --- |
| `session_id` | `string` | `"01M4WQFX6YM2X5V8T4N6R1C0DZ"` | Kennung der Session als ULID mit 26 Zeichen. Sortiert nach der Startzeit und bleibt gleich, wenn Seitenaufrufe dazukommen. |
| `client_id` | `string` | Siehe [Beispiel](#beispiel) | Pseudonymisierte Kennung des Besuchers, die sich täglich ändert und je Konto verschieden ist. |
| `company_id` | `string` | `"41ea486a9c95"` | Das [Unternehmen](https://webmetic.de/docs/api/datenmodell/company) des Besuchs. Nur in `/session`. |
| `company_name` | `string` | `"Bergquell Mineralbrunnen GmbH"` | Name des Unternehmens. Nur in `/session`. |
| `timestamp` | `string` | `"2026-10-14T08:12:05.214000"` | Beginn der Session: der erste Seitenaufruf, in UTC. |
| `weburl` | `string` | `"https://ihre-website.de"` | Protokoll und Host Ihrer Website, ohne Pfad. |
| `utm_source` | `string` | `"linkedin"` | Quelle des Besuchs aus der Adresse oder der verweisenden Website. `"(direct)"`, wenn keine Quelle erkennbar ist. |
| `utm_medium` | `string` | `"social"` | Medium des Besuchs. `"(none)"`, wenn keine Quelle erkennbar ist. |
| `utm_campaign` | `string` | `"messe-2026"` | Kampagne aus der Adresse des ersten Seitenaufrufs. |
| `utm_term` | `string` | `"mineralwasser"` | Begriff aus der Adresse des ersten Seitenaufrufs. |
| `utm_content` | `string` | `"banner-oben"` | Inhalt aus der Adresse des ersten Seitenaufrufs. |
| `utm_campaign_id` | `string` | `"4711"` | Kampagnen-ID aus der Adresse des ersten Seitenaufrufs. |
| `click_id` | `string` | `"Cj0KCQjwx8a2BhD"` | Klick-ID einer Anzeige aus der Adresse des ersten Seitenaufrufs. |
| `click_type` | `string` | | Art der Klick-ID in `click_id`. |
| `gci` | `string` | `"1234567890.1728893525"` | Client-ID von Google Analytics aus dem Cookie `_ga` Ihrer Website. Keine Klick-ID. |
| `gsi` | `string` | `"1728893525"` | Session-ID von Google Analytics 4 aus dem Cookie Ihrer Website. |
| `gsn` | `string` | `"3"` | Session-Nummer von Google Analytics 4 aus dem Cookie Ihrer Website. |
| `session_duration` | `number` | `309.0` | Dauer des Besuchs in Sekunden: vom ersten bis zum letzten Seitenaufruf plus die Zeit auf der letzten Seite. |
| `session_time` | `number` | `103.0` | Durchschnittliche Zeit pro Seitenaufruf in Sekunden, also `session_duration` geteilt durch die Zahl der Seitenaufrufe. Nicht die Gesamtdauer. |
| `session_engagement` | `number` | `284.0` | Aktive Zeit in Sekunden: die Summe der Zeit, die der Browser auf jeder Seite als aktiv gemessen hat. Wenn dieser Wert fehlt, zählt die Zeit bis zum nächsten Seitenaufruf. |
| `user_agent_browser` | `object` | `{"family": "Chrome", "version": "130.0.0"}` | Browser mit Name und Version. |
| `user_agent_os` | `object` | `{"family": "Windows", "version": "11"}` | Betriebssystem mit Name und Version. |
| `user_agent_device` | `object` | `{"family": "Other"}` | Gerät, dazu `brand` und `model`, wenn bekannt. |
| `user_agent_category` | `string` | `"desktop"` | Geräteklasse: `"desktop"`, `"mobile"`, `"tablet"`, `"bot"` oder `"unknown"`. |
| `visitor_city` | `string` | `"Freising"` | Ort des Netzwerks, über das der Besuch kam. Nicht der Wohnort einer Person. |
| `visitor_zip` | `string` | `"85354"` | Postleitzahl des Netzwerks. |
| `visitor_country` | `string` | `"Deutschland"` | Land des Netzwerks, deutscher Name. |
| `visitor_country_code` | `string` | `"DE"` | Land des Netzwerks als Code nach ISO 3166-1 alpha-2. Kann fehlen, auch wenn `visitor_country` gesetzt ist. |
| `user_data` | `array` | | Die Seitenaufrufe der Session. Nicht in `/session`. |
| `blurred` | `boolean` | `true` | Nur im Free-Plan bei verborgenen Unternehmen in `/session`. |

Quelle, Medium, Kampagne und Klick-ID gelten für die ganze Session und stammen aus ihrem ersten Seitenaufruf. Mehr dazu unter [Kampagnen und Kanäle](https://webmetic.de/docs/visitor-intelligence/kampagnen-und-kanaele).

## Seitenaufrufe [#seitenaufrufe]

Die Seitenaufrufe einer Session stehen in `user_data`, einer Liste von Objekten. Jedes Objekt beschreibt einen Seitenaufruf mit Adresse, Titel, Zeit und Ereignissen. Alle Felder stehen unter [Page View](https://webmetic.de/docs/api/datenmodell/page-view).

Eine Session hat kein Feld für die Zahl ihrer Seitenaufrufe. Zählen Sie dafür die Einträge in `user_data`.

`/session` liefert keine Seitenaufrufe. Dafür steht `/session_user_data` mit einer Zeile pro Seitenaufruf bereit. Jede Zeile trägt die `session_id`, über die Sie die Zeile der Session zuordnen.

## Felder je Endpunkt [#felder-je-endpunkt]

| Endpunkt | Eine Zeile | Felder der Session |
| --- | --- | --- |
| `/session` | Eine Session | Alle Felder mit `company_id` und `company_name`, ohne `user_data` |
| `/session_user_data` | Ein Seitenaufruf | Nur die `session_id` |
| `/company-sessions` | Ein Unternehmen | Sessions in `sessions` mit `user_data`; `company_id` und `company_name` stehen am Unternehmen |
| `/intensive-visits`, `/returning-visits`, `/new-visits` | Ein Unternehmen | Sessions in `sessions` mit `user_data`; jedes Feld ist vorhanden, ohne Wert `null` |
| Webhook-Ereignisse | Ein Ereignis | Eine Session in `data.visit`, mit denselben Feldern wie die drei Endpunkte darüber |

In Webhook-Zustellungen tragen Zeitangaben ein `Z`, in API-Antworten nicht. Was die drei Besuchsarten auszeichnet, steht unter [Besuchsarten](https://webmetic.de/docs/api/datenmodell/besuchsarten).

## Beispiel [#beispiel]

Der Besuch begann auf `https://ihre-website.de/preise?utm_source=linkedin&utm_medium=social&utm_campaign=messe-2026` und hatte drei Seitenaufrufe.

```json title="GET /session"
{
  "company_id": "41ea486a9c95",
  "company_name": "Bergquell Mineralbrunnen GmbH",
  "session_id": "01M4WQFX6YM2X5V8T4N6R1C0DZ",
  "client_id": "14e382cf709a614559666137b3d1dfcefa99b1e7ecf93400cc9e2cc4822619d3",
  "timestamp": "2026-10-14T08:12:05.214000",
  "weburl": "https://ihre-website.de",
  "utm_source": "linkedin",
  "utm_medium": "social",
  "utm_campaign": "messe-2026",
  "session_duration": 309.0,
  "session_time": 103.0,
  "session_engagement": 284.0,
  "user_agent_browser": { "family": "Chrome", "version": "130.0.0" },
  "user_agent_os": { "family": "Windows", "version": "11" },
  "user_agent_device": { "family": "Other" },
  "user_agent_category": "desktop",
  "visitor_city": "Freising",
  "visitor_zip": "85354",
  "visitor_country": "Deutschland",
  "visitor_country_code": "DE"
}
```

Zwischen dem ersten und dem letzten Seitenaufruf lagen 245 Sekunden, und auf der letzten Seite maß der Browser 64 Sekunden. Das ergibt eine Dauer von 309 Sekunden und 103 Sekunden pro Seitenaufruf.

## Sonderfälle [#sonderfälle]

- **Fehlende Werte**: In `/session` und `/company-sessions` fehlt ein Feld ohne Wert, aber es kann auch `null` sein. In den Feeds und in Webhooks ist jedes Feld vorhanden, ohne Wert als `null`.
- **Nicht gemessene Zeit**: Wenn es auf der letzten Seite keine Interaktion gab und der Browser keine aktive Zeit gesendet hat, kann Webmetic die Zeit dort nicht messen. Dann setzt Webmetic einen geschätzten Wert von wenigen Sekunden ein, in `time_spent` und in `session_duration`.
- **Reihenfolge**: `/session` und `/company-sessions` liefern Sessions in keiner festen Reihenfolge. Sortieren Sie selbst nach `timestamp` oder `session_id`. In einer Zeile der Feeds stehen die Sessions vom ältesten zum neuesten. Mehr dazu unter [Paginierung](https://webmetic.de/docs/api/paginierung).
- **Zeitraum**: `from_date` und `to_date` filtern nach dem Beginn der Session, auch in `/session_user_data`. Mehr dazu unter [Zeiträume und Zeitzonen](https://webmetic.de/docs/api/zeitraeume-und-zeitzonen).
- **Mehrere Tage**: Wegen der täglich neuen `client_id` können Sie einem Besucher nicht über mehrere Tage folgen. Verbinden Sie Sessions über die `company_id`.
- **Free-Plan**: Bei Unternehmen, die Sie im Free-Plan nicht sehen, hat eine Session in `/session` nur `session_id`, `company_id`, `timestamp`, einen Platzhalter als `company_name` und `blurred: true`. Mehr dazu unter [Pläne](https://webmetic.de/docs/konto/plaene).

## Verwendet von [#verwendet-von]

- **Endpunkte**: [`GET /session`](https://webmetic.de/docs/api/referenz/visitor-intelligence/session), [`GET /session_user_data`](https://webmetic.de/docs/api/referenz/visitor-intelligence/session-user-data), [`GET /company-sessions`](https://webmetic.de/docs/api/referenz/visitor-intelligence/company-sessions), [`GET /intensive-visits`](https://webmetic.de/docs/api/referenz/visitor-intelligence/intensive-visits), [`GET /returning-visits`](https://webmetic.de/docs/api/referenz/visitor-intelligence/returning-visits) und [`GET /new-visits`](https://webmetic.de/docs/api/referenz/visitor-intelligence/new-visits).
- **Webhooks**: `company.identified`, `company.returned`, `company.intensive_visit` und `segment.entered` tragen die Session in `data.visit`. Mehr dazu unter [Webhooks](https://webmetic.de/docs/api/webhooks).
- **KI-Assistent**: Auch der [KI-Assistent](https://webmetic.de/docs/ki-assistent/tools-und-prompts) ruft die Besuche eines Unternehmens ab, mit dem Tool `get_company_activity`.