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

For example, someone from Bergquell Mineralbrunnen reaches your website through a link on LinkedIn in the morning and reads the pricing page, a product page, and the contact page. That makes one session with three page views.

If the same person reads on in the afternoon, a second session starts. On the product pages of these docs, a session is called a visit.

## When a session starts [#when-a-session-starts]

Webmetic starts a new session in these cases:

- A visitor views a page for the first time that day.
- More than 30 minutes have passed since their last page view.
- A new day begins, counted in UTC. In Germany that is at 1 a.m. in winter and 2 a.m. in summer.
- The page address carries campaign parameters such as `utm_source` or a click ID such as `gclid`, and the source or medium differs from the previous page view.

For the campaign rule, a direct visit and a link from your own website don't count as a change. After 30 minutes or on a new day, a direct visit does start a new session.

Signals sent when someone leaves a page, for example about scroll depth, don't count as page views.

A session belongs to exactly one visitor, one website, and one Webmetic account. Subdomains such as `shop.your-website.com` count as the same website as `your-website.com`. No session runs past midnight UTC.

The API only returns sessions that Webmetic has assigned to a company. Visits after an opt-out are also missing, and so are new visits from companies you exclude with the [domain blacklist or the organization types](https://webmetic.de/docs/en/konto/domain-blacklist). Earlier visits of these companies stay in the API.

A session keeps its `session_id` when more page views are added later, so store sessions with the `session_id` as the key and overwrite existing entries.

## Fields [#fields]

| Field | Type | Example | Description |
| --- | --- | --- | --- |
| `session_id` | `string` | `"01M4WQFX6YM2X5V8T4N6R1C0DZ"` | ID of the session as a 26-character ULID. Sorts by start time and stays the same when page views are added. |
| `client_id` | `string` | See [example](#example) | Pseudonymized visitor ID, which changes daily and differs per account. |
| `company_id` | `string` | `"41ea486a9c95"` | The [company](https://webmetic.de/docs/en/api/datenmodell/company) of the visit. Only in `/session`. |
| `company_name` | `string` | `"Bergquell Mineralbrunnen GmbH"` | Name of the company. Only in `/session`. |
| `timestamp` | `string` | `"2026-10-14T08:12:05.214000"` | Start of the session: the first page view, in UTC. |
| `weburl` | `string` | `"https://your-website.com"` | Protocol and host of your website, without a path. |
| `utm_source` | `string` | `"linkedin"` | Source of the visit, from the address or the referring website. `"(direct)"` when no source can be found. |
| `utm_medium` | `string` | `"social"` | Medium of the visit. `"(none)"` when no source can be found. |
| `utm_campaign` | `string` | `"messe-2026"` | Campaign from the address of the first page view. |
| `utm_term` | `string` | `"mineralwasser"` | Term from the address of the first page view. |
| `utm_content` | `string` | `"banner-oben"` | Content from the address of the first page view. |
| `utm_campaign_id` | `string` | `"4711"` | Campaign ID from the address of the first page view. |
| `click_id` | `string` | `"Cj0KCQjwx8a2BhD"` | Ad click ID from the address of the first page view. |
| `click_type` | `string` | | Type of the click ID in `click_id`. |
| `gci` | `string` | `"1234567890.1728893525"` | Google Analytics client ID from your website's `_ga` cookie. Not a click ID. |
| `gsi` | `string` | `"1728893525"` | Google Analytics 4 session ID from your website's cookie. |
| `gsn` | `string` | `"3"` | Google Analytics 4 session number from your website's cookie. |
| `session_duration` | `number` | `309.0` | Length of the visit in seconds: from the first to the last page view, plus the time on the last page. |
| `session_time` | `number` | `103.0` | Average time per page view in seconds, that is `session_duration` divided by the number of page views. Not the total length. |
| `session_engagement` | `number` | `284.0` | Active time in seconds: the sum of the time the browser measured as active on each page. When that value is missing, the time until the next page view counts. |
| `user_agent_browser` | `object` | `{"family": "Chrome", "version": "130.0.0"}` | Browser with name and version. |
| `user_agent_os` | `object` | `{"family": "Windows", "version": "11"}` | Operating system with name and version. |
| `user_agent_device` | `object` | `{"family": "Other"}` | Device, plus `brand` and `model` when known. |
| `user_agent_category` | `string` | `"desktop"` | Device class: `"desktop"`, `"mobile"`, `"tablet"`, `"bot"`, or `"unknown"`. |
| `visitor_city` | `string` | `"Freising"` | City of the network the visit came from. Not where a person lives. |
| `visitor_zip` | `string` | `"85354"` | Postal code of the network. |
| `visitor_country` | `string` | `"Deutschland"` | Country of the network, name in German. |
| `visitor_country_code` | `string` | `"DE"` | Country of the network as an ISO 3166-1 alpha-2 code. Can be missing even when `visitor_country` is set. |
| `user_data` | `array` | | The page views of the session. Not in `/session`. |
| `blurred` | `boolean` | `true` | Only on the Free plan, for hidden companies in `/session`. |

Source, medium, campaign, and click ID apply to the whole session and come from its first page view. For details, see [Campaigns and channels](https://webmetic.de/docs/en/visitor-intelligence/kampagnen-und-kanaele).

## Page views [#page-views]

The page views of a session are in `user_data`, a list of objects. Each object describes one page view with its address, title, time, and events. All fields are listed under [Page View](https://webmetic.de/docs/en/api/datenmodell/page-view).

A session has no field for the number of its page views, so count the entries in `user_data` instead.

`/session` returns no page views. For those, use `/session_user_data`, which has one row per page view. Each row carries the `session_id` that links it to its session.

## Fields per endpoint [#fields-per-endpoint]

| Endpoint | One row | Session fields |
| --- | --- | --- |
| `/session` | One session | All fields with `company_id` and `company_name`, without `user_data` |
| `/session_user_data` | One page view | Only the `session_id` |
| `/company-sessions` | One company | Sessions in `sessions` with `user_data`; `company_id` and `company_name` are on the company |
| `/intensive-visits`, `/returning-visits`, `/new-visits` | One company | Sessions in `sessions` with `user_data`; every field is present, `null` without a value |
| Webhook events | One event | One session in `data.visit`, with the same fields as the three endpoints above |

In webhook deliveries, timestamps carry a `Z`; in API responses they don't. What sets the three visit types apart is described under [Visit types](https://webmetic.de/docs/en/api/datenmodell/besuchsarten).

## Example [#example]

The visit started on `https://your-website.com/pricing?utm_source=linkedin&utm_medium=social&utm_campaign=messe-2026` and had three page views.

```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://your-website.com",
  "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"
}
```

There were 245 seconds between the first and the last page view, and the browser measured 64 seconds on the last page. That makes a length of 309 seconds and 103 seconds per page view.

## Edge cases [#edge-cases]

- **Missing values**: In `/session` and `/company-sessions`, a field without a value is left out, but it can also be `null`. In the feeds and in webhooks, every field is present, as `null` without a value.
- **Time not measured**: If there was no interaction on the last page and the browser sent no active time, Webmetic can't measure the time there. Webmetic then uses an estimate of a few seconds, in `time_spent` and in `session_duration`.
- **Order**: `/session` and `/company-sessions` return sessions in no fixed order, so sort them yourself by `timestamp` or `session_id`. Within a row of the feeds, sessions run from oldest to newest. For details, see [Pagination](https://webmetic.de/docs/en/api/paginierung).
- **Time range**: `from_date` and `to_date` filter by the start of the session, in `/session_user_data` too. For details, see [Date ranges and time zones](https://webmetic.de/docs/en/api/zeitraeume-und-zeitzonen).
- **Several days**: Because the `client_id` changes daily, you can't follow a visitor across several days. Link sessions through the `company_id` instead.
- **Free plan**: For companies you can't see on the Free plan, a session in `/session` only has `session_id`, `company_id`, `timestamp`, a placeholder as `company_name`, and `blurred: true`. For details, see [Plans](https://webmetic.de/docs/en/konto/plaene).

## Used by [#used-by]

- **Endpoints**: [`GET /session`](https://webmetic.de/docs/en/api/referenz/visitor-intelligence/session), [`GET /session_user_data`](https://webmetic.de/docs/en/api/referenz/visitor-intelligence/session-user-data), [`GET /company-sessions`](https://webmetic.de/docs/en/api/referenz/visitor-intelligence/company-sessions), [`GET /intensive-visits`](https://webmetic.de/docs/en/api/referenz/visitor-intelligence/intensive-visits), [`GET /returning-visits`](https://webmetic.de/docs/en/api/referenz/visitor-intelligence/returning-visits), and [`GET /new-visits`](https://webmetic.de/docs/en/api/referenz/visitor-intelligence/new-visits).
- **Webhooks**: `company.identified`, `company.returned`, `company.intensive_visit`, and `segment.entered` carry the session in `data.visit`. For details, see [Webhooks](https://webmetic.de/docs/en/api/webhooks).
- **AI assistant**: The [AI assistant](https://webmetic.de/docs/en/ki-assistent/tools-und-prompts) also retrieves a company's visits, with the tool `get_company_activity`.