Objectives

Use c3d_objective_results() to fetch completion data for Objectives defined in your Cognitive3D project. The function returns aggregate results at the objective level, or optionally breaks them down step-by-step when group_by="steps".

Dynamic object SDK IDs referenced in step details are resolved to friendly names automatically.

Function signature

python c3d_objective_results( project_id=None, objective_id=None, objective_version_id=None, group_by="version", start_date=None, end_date=None, exclude_test=True, exclude_idle=True, output="polars", warn_empty=True, )

Parameters

Parameter	Type	Default	Description
project_id	Integer	from c3d_project()	Cognitive3D project ID
objective_id	Integer	None	Filter to a specific objective by ID
objective_version_id	Integer	None	Filter to a specific objective version by ID
group_by	String	"version"	Group results by "version" for objective-level results, or "steps" for step-level detail
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
output	String	"polars"	"polars" (default) or "pandas"
warn_empty	Boolean	True	Emit a UserWarning when 0 rows are returned

Output columns

Objective-level results (group_by="version")

Column	Description
objective_id	Unique objective identifier
objective_name	Human-readable objective name
objective_version_id	Objective version identifier
version_number	Display version number (Version 1, Version 2, etc.)
version_is_active	Whether this version is currently active
succeeded	Number of sessions where the objective was completed
failed	Number of sessions where the objective was failed
completion_rate	Proportion of sessions that succeeded

Step-level results (group_by="steps")

Column	Description
objective_id	Unique objective identifier
objective_name	Human-readable objective name
objective_version_id	Objective version identifier
version_number	Display version number
step_number	Position of the step within the objective
step_type	Type of step (see below)
step_detail	Step detail — e.g. event name, gaze target, or object name
step_name	Human-readable step name
succeeded	Number of sessions that completed this step
failed	Number of sessions that failed this step
step_completion_rate	Proportion of sessions that completed this step
avg_completion_time_s	Average time from session start to step completion (seconds)
avg_step_duration_s	Average duration of active time spent on this step (seconds)

Step types

Step Type	Description
eventstep	Triggered by a custom event
exitpollstep	Based on an ExitPoll survey response
gazestep	Triggered by gazing at an object or area
fixationstep	Triggered by a fixation on a target
mediapointstep	Triggered by a media interaction

For gazestep, fixationstep, and mediapointstep, step_detail contains the friendly Dynamic Object name resolved from the SDK ID.

Note

version_number is derived by ranking objective_version_id ascending within each objective. Version 1 is the oldest version, matching the label shown on the Cognitive3D Dashboard.

Examples

```python import cognitive3dpy as c3d

All objectives, objective-level results

results = c3d.c3d_objective_results()

Step-level breakdown

detailed = c3d.c3d_objective_results(group_by="steps")

Filter to a specific objective

results = c3d.c3d_objective_results(objective_id=268)

Specific objective with step detail

detailed = c3d.c3d_objective_results( objective_id=268, group_by="steps", )

Date range filter

results = c3d.c3d_objective_results( start_date="2025-01-01", end_date="2025-06-01", ) ```

Working with objective data

The following examples show how to identify bottlenecks and compare results across versions:

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

results = c3d.c3d_objective_results(group_by="steps")

Find the step with the lowest completion rate per objective

bottlenecks = ( results .sort("step_completion_rate") .group_by("objective_name") .first() .select("objective_name", "step_name", "step_completion_rate") )

Compare completion rates across objective versions

( c3d.c3d_objective_results(group_by="version") .select("objective_name", "version_number", "completion_rate") .sort(["objective_name", "version_number"]) ) ```

---

Session Objectives

Use c3d_session_objectives() to fetch per-session objective step results. Each row represents one step outcome for one session, making it easy to trace how individual participants progressed through an objective.

Function signature

python c3d_session_objectives( project_id=None, n=500, scene_id=None, scene_version_id=None, start_date=None, end_date=None, exclude_test=True, exclude_idle=True, min_duration=0, 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 per scene version
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	0	Minimum session duration in seconds. Sessions shorter than this value are excluded from results.
output	String	"polars"	"polars" (default) or "pandas"
warn_empty	Boolean	True	Emit a UserWarning when 0 rows are returned

Output columns

Column	Description
project_id	Cognitive3D project ID
scene_id	Scene UUID
scene_name	Human-readable scene name
scene_version_id	Scene version identifier
session_id	Unique session identifier
participant_id	Participant identifier
session_date	Session start time
objective_id	Unique objective identifier
objective_name	Human-readable objective name
step_number	Position of the step within the objective
step_description	Human-readable step description
step_timestamp	Timestamp when the step was completed (UTC)
step_duration	Time spent on this step in milliseconds
step_duration_sec	Time spent on this step in seconds
step_result	Outcome of the step: "succeeded" or "failed"

Examples

```python import cognitive3dpy as c3d

Per-session step results for all objectives, last 30 days

objective_by_session = c3d.c3d_session_objectives()

Filter to a specific date range

objective_by_session = c3d.c3d_session_objectives( start_date="2025-01-01", end_date="2025-06-01", )

Filter to a specific scene

objective_by_session = c3d.c3d_session_objectives( scene_id="de704574-b03f-424e-be87-4985f85ed2e8", )

Only include sessions longer than 2 minutes

objective_by_session = c3d.c3d_session_objectives( start_date="2025-01-01", min_duration=120, ) ```

Working with session objective data

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

objective_by_session = c3d.c3d_session_objectives(start_date="2025-01-01")

Count successes and failures per step

( objective_by_session .group_by("objective_name", "step_number", "step_description") .agg( (pl.col("step_result") == "succeeded").sum().alias("succeeded"), (pl.col("step_result") == "failed").sum().alias("failed"), ) .sort(["objective_name", "step_number"]) )

Average step duration per step

( objective_by_session .group_by("objective_name", "step_number", "step_description") .agg(pl.col("step_duration_sec").mean().alias("avg_duration_sec")) .sort(["objective_name", "step_number"]) )

Filter to a specific participant

participant_steps = objective_by_session.filter( pl.col("participant_id") == "user-42" ) ```

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.