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

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

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:

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

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

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

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.