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

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

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:

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.