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 include_steps = TRUE.

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

Function Signature

c3d_objective_results(
  project_id = NULL,
  objective_id = NULL,
  objective_version_id = NULL,
  slice_by = c("objective_version", "objective"),
  include_steps = FALSE,
  exclude_test = TRUE,
  exclude_idle = TRUE,
  start_date = NULL,
  end_date = NULL
)

Parameters

Parameter	Type	Default	Description
`project_id`	Integer	from `c3d_project()`	Cognitive3D project ID
`objective_id`	Integer	`NULL`	Filter to a specific objective by ID
`objective_version_id`	Integer	`NULL`	Filter to a specific objective version by ID
`slice_by`	Character	`"objective_version"`	Group results by `"objective_version"` or `"objective"`
`include_steps`	Logical	`FALSE`	When `TRUE`, return step-level detail instead of objective-level
`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"`)

Output Columns

Objective-Level Results (`include_steps = FALSE`)

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 (`include_steps = TRUE`)

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 to complete the step (seconds)
`avg_step_duration_s`	Average 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

# All objectives, objective-level results
results <- c3d_objective_results()

# With step-level breakdown
detailed <- c3d_objective_results(include_steps = TRUE)

# Group results by objective (collapse all versions)
by_objective <- c3d_objective_results(slice_by = "objective")

# Filter to a specific objective
results <- c3d_objective_results(objective_id = 268)

# Specific objective with step detail
detailed <- c3d_objective_results(
  objective_id  = 268,
  include_steps = TRUE
)

# Date range filter
results <- c3d_objective_results(
  start_date = "2025-01-01",
  end_date   = "2025-06-01"
)

Working with Objective Data

library(dplyr)

results <- c3d_objective_results(include_steps = TRUE)

# Find the step with the lowest completion rate per objective
results |>
  group_by(objective_name) |>
  slice_min(step_completion_rate, n = 1) |>
  select(objective_name, step_name, step_completion_rate)

# Compare completion rates across objective versions
c3d_objective_results(slice_by = "objective_version") |>
  select(objective_name, version_number, completion_rate) |>
  arrange(objective_name, version_number)

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.