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

bash pip install cognitive3dpy

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

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

```bash

Option 1: .env file (recommended)

Add this line to a .env file in your project directory:

C3D_API_KEY=your_api_key_here ```

```bash

Option 2: Shell environment variable

export C3D_API_KEY=your_api_key_here ```

```python 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/...).

python 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:

```python 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:

python c3d.c3d_set_timeout(60) # 60 seconds

Or set the C3D_TIMEOUT environment variable before your session starts:

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