Sessions

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

Function Signature

c3d_sessions(
  project_id = NULL,
  n = 500,
  session_type = c("project", "scene"),
  scene_id = NULL,
  scene_version_id = NULL,
  start_date = NULL,
  end_date = NULL,
  exclude_test = TRUE,
  exclude_idle = TRUE,
  min_duration = NULL,
  compact = TRUE
)

Parameters

Parameter	Type	Default	Description
project_id	Integer	from c3d_project()	Cognitive3D project ID
n	Integer	500	Maximum number of sessions to return (max 500)
session_type	Character	"project"	"project" for one row per session; "scene" for one row per scene visited during the session
scene_id	Character	NULL	Filter to a specific scene by its UUID
scene_version_id	Integer	NULL	Filter to a specific scene version ID
start_date	Date / string	30 days ago	Start of the date range ("YYYY-MM-DD")
end_date	Date / string	now	End of the date range ("YYYY-MM-DD")
exclude_test	Logical	TRUE	Filter out sessions tagged as test
exclude_idle	Logical	TRUE	Filter out sessions tagged as junk or idle
min_duration	Numeric	NULL	Minimum session duration in seconds
compact	Logical	TRUE	Return a curated set of ~40 columns; set to FALSE for all columns

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 tibble 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 will be converted to snake_case.

Examples

# Last 100 sessions (last 30 days, default filters)
sessions <- c3d_sessions(n = 100)

# Sessions within a specific date range, all columns
sessions <- 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_sessions(session_type = "scene")

# Filter to a specific scene
scene_data <- c3d_sessions(
  session_type = "scene",
  scene_id = "de704574-b03f-424e-be87-4985f85ed2e8"
)

# Filter to a specific scene version
scene_data <- c3d_sessions(
  session_type = "scene",
  scene_version_id = 7011
)

# Only sessions longer than 2 minutes
long_sessions <- c3d_sessions(min_duration = 120)

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.