# Visits (https://webmetic.de/docs/api/referenz/visitor-intelligence/session)

## GET /session

Retrieves detailed session information for a specified domain within a given time range.

This endpoint provides comprehensive data about user sessions, including technical details about the user's
device, browser, and interaction with the website. It also includes company identification for each session.

Parameters:
- domain (str): The domain name for which you want to retrieve session information.
- from_date (str, optional): The starting date and time for the session data range. Accepts ISO 8601 format
or relative dates like '-30 days'. Default is '-30 days'.
- to_date (str, optional): The ending date and time for the session data range. Accepts ISO 8601 format
or 'now' for the current date and time. Default is 'now'.
- page (int, optional): The page number of results to retrieve. Default is 1.
- page_size (int, optional): The number of entries to retrieve per page, up to 10000. Default is 10000.

Returns:
A JSON object containing:
1. Pagination information:
- total: Total number of session entries
- page_total: Total number of pages
- isFirst: Boolean indicating if it's the first page
- current: Current page number
- isLast: Boolean indicating if it's the last page
- page_size: Number of entries per page
2. Result: An array of session objects, each containing:
- company_id: Unique identifier for the company associated with the session
- company_name: Name of the company associated with the session
- session_id: Unique identifier for the session
- client_id: Unique identifier for the client
- aid: Account identifier
- weburl: URL of the website visited
- timestamp: Date and time when the session occurred
- user_agent: Full user agent string
- platform: Operating system platform
- screen_resolution: Screen resolution of the user's device
- color_depth: Color depth of the user's screen
- viewport: Viewport size of the browser
- cookies_enabled: Boolean indicating if cookies are enabled
- connection_type: Type of internet connection (e.g., 4g, wifi)
- color_scheme: Color scheme preference (e.g., light, dark)
- user_language: User's preferred language
- utm_source: UTM source parameter
- utm_medium: UTM medium parameter
- gci: Google Click Identifier
- gsi: Google Session Identifier
- gsn: Google Session Number
- user_agent_browser: Object containing browser family and version
- user_agent_os: Object containing OS family and version
- user_agent_device: Object containing device family
- user_agent_category: Category of the user agent (e.g., desktop, mobile)
- session_duration: Total duration of the session
- session_time: Average time per page view of the session, in seconds

Note: This endpoint is rate-limited to 1 request per second.

### Parameter

| Name | Ort | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `domain` | query | string | ja |  |
| `from_date` | query | string | nein | Starting DateTime format or relative dates like '-30 days', '-1 hour', '-5 minutes'. Examples: '2023-01-01', '-7 days', '-12 hours', '-5 minutes', 'now' |
| `to_date` | query | string | nein | Ending DateTime format or 'now' for the current date/time. Examples: '2023-01-31', 'now' |
| `page` | query | integer | nein | Selected result page, starting at 1 |
| `page_size` | query | integer | nein | Number of entries per page, from 1 up to a maximum of 10000 |

### Antworten

| Status | Beschreibung |
| --- | --- |
| 200 | One entry per visit; missing fields are absent |
| 400 | INVALID_DATE: from_date or to_date cannot be read |
| 403 | API_KEY_MISSING, API_KEY_INVALID, API_KEY_NOT_FOUND, or API_KEY_NOT_AUTHORIZED: the domain is not a website of your account (send it exactly as listed there) |
| 422 | VALIDATION_ERROR: a parameter is missing or out of range (page from 1, page_size 1 to 10000); `errors` lists each problem |
| 429 | RATE_LIMITED: more than one request per second to this endpoint |
| 500 | INTERNAL_ERROR: unexpected server error |

Felder der Antwort 200:

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `pagination` | Pagination[] | ja | Always one entry |
| `pagination[].total` | integer | ja | Entries over all pages |
| `pagination[].page_total` | integer | ja | Number of pages; 0 on an empty result |
| `pagination[].isFirst` | boolean | ja | true on page 1 |
| `pagination[].current` | integer | ja | This page, from 1 |
| `pagination[].isLast` | boolean | ja | true when current >= page_total, also on an empty result |
| `pagination[].page_size` | integer | ja | Entries per page as requested |
| `result` | SessionRow[] | ja | One entry per visit |
| `result[].company_id` | string \| null | nein | Webmetic's id of the company (12 characters). /contacts takes it. |
| `result[].company_name` | string \| null | nein | Company name. On Free a hidden company reads 'Verborgenes Unternehmen'. |
| `result[].timestamp` | string \| null | nein | Start of the visit, UTC, ISO 8601 without offset, e.g. 2026-10-20T08:20:26.384000 |
| `result[].session_id` | string \| null | nein | Id of the visit |
| `result[].client_id` | string \| null | nein | Pseudonymous visitor id; changes daily and differs per Webmetic account |
| `result[].weburl` | string \| null | nein | Your website that was visited |
| `result[].utm_source` | string \| null | nein | utm_source of the landing URL |
| `result[].utm_medium` | string \| null | nein | utm_medium of the landing URL |
| `result[].utm_campaign` | string \| null | nein | utm_campaign of the landing URL |
| `result[].utm_term` | string \| null | nein | utm_term of the landing URL |
| `result[].utm_content` | string \| null | nein | utm_content of the landing URL |
| `result[].utm_campaign_id` | string \| null | nein | Campaign id of the landing URL (utm_id) |
| `result[].click_id` | string \| null | nein | Ad click id from the landing URL |
| `result[].click_type` | string \| null | nein | Parameter the click id came from, e.g. gclid |
| `result[].gci` | string \| null | nein | Google Analytics client id, when the site uses Google Analytics |
| `result[].gsi` | string \| null | nein | Google Analytics session id |
| `result[].gsn` | string \| null | nein | Google Analytics session number |
| `result[].session_duration` | number \| null | nein | Length of the whole visit in seconds; 30 or more is an intensive visit |
| `result[].session_time` | number \| null | nein | Average seconds per page view of the visit |
| `result[].session_engagement` | number \| null | nein | Engagement time in seconds as measured (raw value, can be negative) |
| `result[].user_agent_browser` | UserAgentPart \| null | nein | Browser |
| `result[].user_agent_os` | UserAgentPart \| null | nein | Operating system |
| `result[].user_agent_device` | UserAgentPart \| null | nein | Device |
| `result[].user_agent_category` | string \| null | nein | desktop, mobile or tablet |
| `result[].visitor_city` | string \| null | nein | City of the visitor's network location |
| `result[].visitor_country` | string \| null | nein | Country of the visitor's network location, as a name |
| `result[].visitor_zip` | string \| null | nein | Postal code of the visitor's network location |
| `result[].visitor_country_code` | string \| null | nein | Country of the visitor's network location, ISO 3166-1 alpha-2 |
| `result[].blurred` | boolean \| null | nein | Only on Free, for a company past the month's readable ones: true, and only the ids and visit times are given |

### Beispiel

```bash
curl -X GET 'https://hub.webmetic.de/session?domain=website.example' \
  -H 'Authorization: wmtc_IHR_API_SCHLUESSEL'
```