Events

Use c3d_events() to fetch per-event data with session context attached. Events are unnested from sessions — one row per event. Dynamic Object SDK IDs are resolved to friendly names automatically, and scene version IDs are resolved to scene names.

Function signature

c3d_events(
    project_id=None,
    n=500,
    start_date=None,
    end_date=None,
    exclude_test=True,
    exclude_idle=True,
    min_duration=None,
    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 fetch events from
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
output	String	"polars"	"polars" (default) or "pandas"
warn_empty	Boolean	True	Emit a UserWarning when 0 rows are returned

Output columns

Column	Description
session_id	Session the event belongs to
participant_id	Participant identifier
user_key	User key associated with the session
device_id	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	X coordinate of the event position
position_y	Y coordinate of the event position
position_z	Z coordinate of the event position
object_id	Raw dynamic object SDK ID
object	Resolved friendly name of the dynamic object
scene_version_id	Scene version identifier
scene_name	Resolved human-readable scene name
prop_*	Dynamic columns for custom event properties

Custom event properties are flattened into individual prop_* columns — one column per property key.

Warning

The Cognitive3D API caps event retrieval at 8,000 events per session. Sessions that exceed this limit are returned with a truncated event list. The function emits a warning listing the affected session IDs when this cap is hit.

Examples

import cognitive3dpy as c3d

# Events from the last 30 days (default)
events = c3d.c3d_events()

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

# Return as a pandas DataFrame
events = c3d.c3d_events(output="pandas")

Working with event data

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

import polars as pl
import cognitive3dpy as c3d

events = c3d.c3d_events(start_date="2025-01-01")

# Count events by name
event_counts = (
    events
    .group_by("event_name")
    .agg(pl.len().alias("count"))
    .sort("count", descending=True)
)

# Filter to a specific event type
grab_events = events.filter(pl.col("event_name") == "GrabObject")

# Summarise average event position by event name
events.group_by("event_name").agg(
    pl.col("position_x").mean().alias("avg_x"),
    pl.col("position_y").mean().alias("avg_y"),
    pl.col("position_z").mean().alias("avg_z"),
)

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.