rybbit-mcp

List Sessions

rybbit_list_sessions

Read-onlyIdempotent

List and filter website sessions with pagination and IP filtering, returning session details including user info, device, location, pages visited, and bounce status.

Instructions

List sessions for a site with filtering and pagination. Returns session ID, user info, device, location, pages visited, duration, bounce status, and IP address (if site has trackIp enabled). Supports client-side IP filtering.

Input Schema

TableJSON Schema

Name	Required	Description
`ip`	No	Filter sessions by IP address (exact or partial match, client-side). Requires site to have trackIp enabled.
`page`	No	Page number, 1-indexed (default: 1)
`limit`	No	Results per page (default: 20-50 depending on endpoint, max 200)
`siteId`	Yes	Site ID (numeric ID or domain identifier)
`endDate`	No	End date in ISO format (YYYY-MM-DD)
`filters`	No	Array of filters. Example: [{parameter:'browser',type:'equals',value:['Chrome']},{parameter:'country',type:'equals',value:['US','DE']}]
`timeZone`	No	IANA timezone (e.g., Europe/Prague). Default: UTC
`startDate`	No	Start date in ISO format (YYYY-MM-DD)
`minDuration`	No	Minimum session duration in seconds.
`identifiedOnly`	No	Only return sessions from identified users. Default: false.
`pastMinutesEnd`	No	Alternative to dates: minutes ago end (default 0 = now)
`pastMinutesStart`	No	Alternative to dates: minutes ago start (e.g., 60 = last hour)

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No	Sessions
`filteredBy`	No	Client-side filter applied (e.g. ip=...)
`scannedPages`	No	Pages scanned when filtering client-side

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.8.1Sep 28, 2026

changedInput schema / properties / filters / items / properties / parameter / description

Previous value: -"Filter dimension. One of: browser, browser_version, operating_system, operating_system_version, language, country, region, city, device_type, device_model, app_version, dimensions, referrer, hostname, pathname, page_title, querystring, event_name, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, entry_page, exit_page, user_id, lat, lon, timezone, vpn, crawler, datacenter, company, company_type, company_domain, asn_org, asn_type, asn_domain, tag. Custom URL parameters use the prefix 'url_param:NAME' (e.g., 'url_param:campaign_id'). Note: user_id filter checks BOTH the device hash (user_id) and app-provided ID (identified_user_id). device_model and app_version are populated only for app-type sites tracked via SDK."New value: +"Filter dimension. One of: browser, browser_version, operating_system, operating_system_version, language, country, region, city, device_type, device_model, app_version, dimensions, referrer, hostname, pathname, page_title, querystring, event_name, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, entry_page, exit_page, user_id, lat, lon, timezone, tag. Custom URL parameters use the prefix 'url_param:NAME' (e.g., 'url_param:campaign_id'). Note: user_id filter checks BOTH the device hash (user_id) and app-provided ID (identified_user_id). device_model and app_version are populated only for mobile-type sites (legacy: app) tracked via SDK."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "description": "Sessions",
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "bounced": {
+            "type": "boolean"
+          },
+          "city": {
+            "type": "string"
+          },
+          "country": {
+            "type": "string"
+          },
+          "device": {
+            "type": "string"
+          },
+          "duration": {
+            "type": "number"
+          },
+          "pagesVisited": {
+            "type": "number"
+          },
+          "sessionId": {
+            "type": "string"
+          },
+          "userId": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "filteredBy": {
+      "description": "Client-side filter applied (e.g. ip=...)",
+      "type": "string"
+    },
+    "scannedPages": {
+      "description": "Pages scanned when filtering client-side",
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedv0.4.3Apr 30, 2026

changedInput schema / properties / filters / items / properties / parameter / description

Previous value: -"Filter dimension: browser, operating_system, language, country, region, city, device_type, referrer, hostname, pathname, page_title, querystring, event_name, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, entry_page, exit_page, user_id. Note: user_id filter checks BOTH the device hash (user_id) and app-provided ID (identified_user_id)."New value: +"Filter dimension. One of: browser, browser_version, operating_system, operating_system_version, language, country, region, city, device_type, device_model, app_version, dimensions, referrer, hostname, pathname, page_title, querystring, event_name, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, entry_page, exit_page, user_id, lat, lon, timezone, vpn, crawler, datacenter, company, company_type, company_domain, asn_org, asn_type, asn_domain, tag. Custom URL parameters use the prefix 'url_param:NAME' (e.g., 'url_param:campaign_id'). Note: user_id filter checks BOTH the device hash (user_id) and app-provided ID (identified_user_id). device_model and app_version are populated only for app-type sites tracked via SDK."

First observedv0.5.2Apr 2, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely useful behavioral context: the enumerated return fields, the conditional presence of IP address gated on the site's trackIp setting, and the caveat that IP filtering happens client-side. These are traits an agent cannot infer from the annotations or schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and followed by the return-shape detail. Dense but every clause adds information; no filler or restated title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't document return values in depth, yet it summarizes them usefully. All 12 parameters are covered by the schema at 100% coverage, and the description adds the one non-obvious behavioral constraint (trackIp-gated IP field, client-side filtering). Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly, including the filter enum values and parameter dimensions. The description's only additional param-related signal is the client-side nature of IP filtering and the trackIp prerequisite, which is marginal over the schema. Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List sessions for a site') plus scope modifiers (filtering, pagination). An agent can distinguish it from the singular sibling rybbit_get_session by the plural session scope, though the description never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied ('for a site with filtering and pagination') but there is no explicit when-to-use vs. when-not guidance or reference to the alternative rybbit_get_session for a single session. It notes the client-side IP filtering capability, which hints at a use case but does not route the agent between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server