Events

Use c3d_events() to fetch custom event records for sessions in your project. Each row in the returned tibble represents one event, with session context attached automatically.

Dynamic object SDK IDs are resolved to friendly names, and scene version IDs are resolved to scene names, so the data is immediately human-readable.

Function Signature

c3d_events(
  project_id = NULL,
  exclude_test = TRUE,
  exclude_idle = TRUE,
  start_date = NULL,
  end_date = NULL,
  min_duration = NULL,
  page_limit = 100,
  max_sessions = 500
)

Parameters

Parameter	Type	Default	Description
project_id	Integer	from c3d_project()	Cognitive3D project ID
exclude_test	Logical	TRUE	Filter out sessions tagged as test
exclude_idle	Logical	TRUE	Filter out sessions tagged as junk or idle
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")
min_duration	Numeric	NULL	Minimum session duration in seconds
page_limit	Integer	100	Number of sessions to fetch per API page
max_sessions	Integer	500	Maximum number of sessions to pull events from

Output Columns

Column	Description
session_id	Unique session identifier
participant_id	Participant identifier
user_key	User key associated with the session
device_id	Unique device identifier
session_date	Session start time
duration_s	Session duration in seconds
event_name	Name of the custom event
event_date	Timestamp of the event
position_x	World-space X position where the event occurred
position_y	World-space Y position where the event occurred
position_z	World-space Z position where the event occurred
object_id	SDK ID of the associated dynamic object (if any)
object	Friendly name of the associated dynamic object
scene_version_id	Scene version identifier
scene_name	Human-readable scene name
prop_*	Dynamic columns for each event property key

Event properties are unpacked into individual prop_* columns, with one column per unique property key found in the data.

Warning

Sessions with more than 8,000 events will have their events capped by the API (eventsLimited = TRUE). The function will emit a warning listing the affected session IDs.

Examples

# Events from the last 30 days (default filters)
events <- c3d_events()

# Events from a specific date range, up to 20 sessions
events <- c3d_events(
  start_date   = "2025-01-01",
  max_sessions = 20
)

# Only sessions longer than 60 seconds
events <- c3d_events(
  min_duration = 60,
  max_sessions = 100
)

# Include test sessions
events <- c3d_events(exclude_test = FALSE)

Working with Event Data

The tibble returned by c3d_events() works naturally with tidyverse tools:

library(dplyr)

events <- c3d_events()

# Count events by name
events |>
  count(event_name, sort = TRUE)

# Summarize events per session
events |>
  group_by(session_id) |>
  summarise(n_events = n(), .groups = "drop")

# Filter to a specific event type
events |>
  filter(event_name == "TaskComplete")

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.