Sessions

Use c3d_sessions() to fetch session-level analytics data for your project. Each row in the returned DataFrame represents one session (or one session-scene combination when using session_type="scene").

Function signature

python c3d_sessions( project_id=None, n=500, session_type="project", scene_id=None, scene_version_id=None, start_date=None, end_date=None, exclude_test=True, exclude_idle=True, min_duration=None, compact=True, output="polars", warn_empty=True, )

Parameters

Parameter	Type	Default	Description
project_id	Integer	from c3d_project()	Cognitive3D project ID
n	Integer	500	Maximum number of sessions to return. When using session_type="scene", this cap is applied per scene version.
session_type	String	"project"	"project" for one row per session; "scene" for one row per scene visited during the session
scene_id	String	None	Filter to a specific scene by its UUID
scene_version_id	Integer	None	Filter to a specific scene version ID
start_date	date / datetime / string / int	30 days ago	Start of the date range ("YYYY-MM-DD")
end_date	date / datetime / string / int	now	End of the date range ("YYYY-MM-DD")
exclude_test	Boolean	True	Filter out sessions tagged as test
exclude_idle	Boolean	True	Filter out sessions tagged as junk or idle
min_duration	Integer	None	Minimum session duration in seconds
compact	Boolean	True	Return a curated set of ~40 columns; set to False for all columns
output	String	"polars"	"polars" (default) or "pandas"
warn_empty	Boolean	True	Emit a UserWarning when 0 rows are returned

Session types

session_type="project" (default)

Returns one row per session. Use this for session-level analysis regardless of which scenes were visited.

session_type="scene"

Returns one row per session-scene combination. When no scene_id or scene_version_id is specified, the function automatically queries the latest version of every scene in your project and combines the results. The n cap is applied per scene.

Output columns

When compact=True (default), the returned DataFrame includes approximately 40 curated columns. Key columns include:

Column	Description
session_id	Unique session identifier
session_date	Session start time (renamed from date)
end_date	Session end time
duration_s	Session duration in seconds (converted from milliseconds)
hmd	Headset model
device_id	Unique device identifier
participant_id	Participant identifier
user_key	User key associated with the session
friendly_name	Human-readable participant name
tags	Session tags
scene_id	Scene UUID
scene_version_id	Scene version identifier
scene_name	Human-readable scene name
c3d_participant_name	Cognitive3D participant name property
c3d_app_name	Application name
c3d_app_version	Application version
c3d_device_type	Device type
c3d_geo_country	Country from geolocation
c3d_geo_city	City from geolocation
c3d_metrics_fps_score	FPS performance score
c3d_metrics_average_fps	Average frames per second
c3d_metrics_presence_score	Presence metric score
c3d_metrics_comfort_score	Comfort metric score

Set compact=False to retrieve all available columns.

Note

Column naming follows these conventions: top-level API fields use snake_case; Cognitive3D properties retain the c3d_ prefix (e.g., c3d_metrics_fps_score). Duration is converted from milliseconds to seconds and stored as duration_s. Custom session properties are converted to snake_case.

Examples

```python import cognitive3dpy as c3d

Last 100 sessions (last 30 days, default filters)

sessions = c3d.c3d_sessions(n=100)

Sessions within a specific date range, all columns

sessions = c3d.c3d_sessions( start_date="2025-01-01", end_date="2025-06-01", compact=False, )

One row per session-scene combination (all scenes, latest versions), last 30 days

scene_data = c3d.c3d_sessions(session_type="scene")

Filter to a specific scene

scene_data = c3d.c3d_sessions( session_type="scene", scene_id="de704574-b03f-424e-be87-4985f85ed2e8", )

Filter to a specific scene version

scene_data = c3d.c3d_sessions( session_type="scene", scene_version_id=7011, )

Only sessions longer than 2 minutes

long_sessions = c3d.c3d_sessions(min_duration=120)

Return as a pandas DataFrame

sessions = c3d.c3d_sessions(n=100, output="pandas") ```

Working with session data

The following examples show how to filter and summarize the returned DataFrame using Polars:

```python import polars as pl import cognitive3dpy as c3d

sessions = c3d.c3d_sessions(n=500)

Count sessions per headset model

sessions.group_by("hmd").agg(pl.len().alias("count")).sort("count", descending=True)

Filter to sessions longer than 5 minutes

long_sessions = sessions.filter(pl.col("duration_s") > 300)

Average session duration per scene

sessions.group_by("scene_name").agg( pl.col("duration_s").mean().alias("avg_duration_s") ).sort("avg_duration_s", descending=True) ```

If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.