Skip to content

Getting Started with the cognitive3dpy Package

cognitive3dpy is a Python client for the Cognitive3D analytics API. It fetches your session data and returns DataFrames ready for analysis, handling authentication, pagination, property flattening, name resolution, and type coercion automatically.

Requirements

  • Python 3.11+: This package requires Python 3.11 or higher. To check your current version: python --version.
  • Cognitive3D Account: You'll need an active Cognitive3D account to obtain your API key and project ID. You can sign up on the Cognitive3D website.

Installation

pip install cognitive3dpy

To enable pandas output (output="pandas"), install with the optional extra:

pip install "cognitive3dpy[pandas]"

Authentication

Load the package and authenticate with your API key. Store your key in a .env file or set it as a shell environment variable — never hardcode credentials in scripts.

# Option 1: .env file (recommended)
# Add this line to a .env file in your project directory:
C3D_API_KEY=your_api_key_here

# Option 2: Shell environment variable
export C3D_API_KEY=your_api_key_here

import cognitive3dpy as c3d

# Reads C3D_API_KEY automatically from the environment
c3d.c3d_auth()

# Or pass the key directly (not recommended for shared scripts)
c3d.c3d_auth("YOUR_API_KEY_HERE")

Note

Your API key can be found in the Cognitive3D Dashboard under Settings → API Keys. Treat it like a password — do not commit it to source control.

Set your project

After authenticating, specify which project you want to query. Your project ID is visible in the Cognitive3D Dashboard URL when viewing a project (e.g., app.cognitive3d.com/project/4460/...).

c3d.c3d_project(4460)  # Replace with your project ID

This sets a session-level default so you don't need to pass project_id to every function call.

Quick start

Once authenticated and your project is set, you can pull data in just a few lines:

import cognitive3dpy as c3d

c3d.c3d_auth()        # reads C3D_API_KEY from environment
c3d.c3d_project(4460) # set default project

# Fetch the last 100 sessions
sessions = c3d.c3d_sessions(n=100)

# Fetch custom events from the last 30 days
events = c3d.c3d_events()

# Fetch objective completion by version
objective_by_version = c3d.c3d_objective_results(group_by="version")

# Fetch objective completion by step
objective_by_steps = c3d.c3d_objective_results(group_by="steps")

# Fetch per-session objective step results
objective_by_session = c3d.c3d_session_objectives()

# Fetch ExitPoll survey response counts
polls = c3d.c3d_exitpoll()

All functions return a polars.DataFrame by default. Pass output="pandas" to receive a pandas.DataFrame instead.

Common parameters

Most data-fetching functions share a consistent set of filter parameters:

Parameter Type Default Description
project_id Integer from c3d_project() Cognitive3D project ID
start_date date / datetime / string / int 30 days ago Start of the date range ("YYYY-MM-DD", epoch timestamp, or date object)
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 (0 for c3d_session_objectives) Minimum session duration to include in results, in seconds
output String "polars" Return format: "polars" for a Polars DataFrame or "pandas" for a pandas DataFrame
warn_empty Boolean True Emit a UserWarning when 0 rows are returned; set to False to suppress

Configuration

The default request timeout is 30 seconds per API call. To increase it:

c3d.c3d_set_timeout(60)  # 60 seconds

Or set the C3D_TIMEOUT environment variable before your session starts:

export C3D_TIMEOUT=60

c3d_set_timeout() takes effect immediately. The environment variable is read once on first import, so it must be set before importing the package.

Next steps

  • Sessions — Fetch session-level data with c3d_sessions().
  • Events — Retrieve custom event records with c3d_events().
  • Objectives — Query objective and step completion with c3d_objective_results().
  • Session Objectives — Fetch per-session objective step results with c3d_session_objectives().
  • ExitPoll — Pull survey response counts with c3d_exitpoll().

intercom 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.