Introducing the Cognitive3D Python Package

Working with XR analytics data often starts the same way: exporting JSON responses from an API, flattening nested structures, resolving identifiers into readable names, and cleaning the data before it can even be analyzed.

In a previous post, we introduced the Cognitive3D R package, which simplifies this workflow for analysts working in R.

Now, we’re bringing the same streamlined approach to Python with the Cognitive3D Python package.

This package allows analysts to retrieve session metrics, events, objectives, and survey responses directly from the Cognitive3D Analytics API and load them into analysis-ready data structures. Instead of writing custom scripts to manage authentication, pagination, and data formatting, analysts can begin exploring XR analytics data in just a few lines of Python.

With just a few lines of code, you can move from an API key to a structured dataset that’s ready to explore in a notebook, dashboard, or analysis pipeline.

For teams already using Python for data science, reporting, or automation, this package makes working with Cognitive3D analytics much more straightforward.

What the Python Package Does

The Cognitive3D Python package provides a simple interface for querying analytics data from the Cognitive3D platform. Under the hood, it communicates with the Cognitive3D API and handles many of the technical details involved in retrieving and structuring the data.

When working directly with APIs, analysts often have to manage pagination across multiple requests, parse nested JSON responses, and resolve internal identifiers into human-readable names. The Python package abstracts these steps away so that the results come back in a clean, structured format.

The data returned by the package is immediately ready for analysis as a DataFrame. This allows analysts to move directly into filtering, aggregating, and visualizing data without needing to write extensive preprocessing code.

By default, the package returns results as Polars DataFrames, a high-performance DataFrame engine designed for working with large datasets. Analysts who prefer more traditional Python workflows can also return results as Pandas DataFrames.

The package also includes sensible defaults that make it easy to begin exploring data quickly, while still providing flexibility for more advanced queries.

Installation

The Python package can be installed directly from the Cognitive3D GitHub repository or via PyPI.

Once installed, it can be used in any Python environment, including notebooks, scripts, or automated workflows.

After installation, the only requirement is a Cognitive3D API key, which is used to authenticate requests to the platform.

Getting an API Key

API keys can be generated from the Cognitive3D dashboard.

Within the dashboard settings, users can create API keys that allow external tools to query analytics data securely. Once generated, the key can be stored in an environment variable or configuration file so it can be accessed by Python scripts without exposing it in code.

This allows teams to integrate analytics workflows into existing data pipelines while maintaining proper credential management.

Querying XR Analytics Data in Python

Once authenticated, the Python client allows you to query several different categories of analytics data.

These include session-level metrics, detailed in-experience events, objective completion data, and exit poll responses. Each query returns structured results that can immediately be explored using common Python analysis tools.

Because the package returns results as DataFrames, analysts can quickly perform tasks like grouping sessions by device type, analyzing event frequency across scenes, or comparing objective completion rates across versions of an experience.

This makes the package particularly useful for exploratory analysis in tools like Jupyter notebooks or for building automated reports.

Many of the package’s query functions also include sensible defaults that make it easy to begin exploring data immediately. For example, if no time range is specified, queries return recent data from the last 30 days so analysts can quickly inspect the latest sessions and interactions without needing to configure additional filters.

Session Data

Session queries provide a high-level overview of how users interact with an experience. Each session represents a user’s visit to an application and includes metrics such as session duration, hardware information, and other contextual properties.

Analyzing session data can reveal patterns in how users engage with an experience. For example, analysts might examine session durations across device types, compare performance metrics between builds, or identify geographic trends in usage.

The Python package simplifies retrieving this information so that analysts can focus on interpreting the results rather than assembling the dataset.

Scene-Level Sessions

In many XR experiences, behaviour can vary significantly between scenes or environments. Understanding how users move through different areas of an experience often requires looking at session data at a more granular level.

The Python package allows sessions to be analyzed at the more granular scene level, returning data for each scene visited during a session. This makes it possible to analyze engagement and performance metrics within specific environments.

For example, analysts might compare how long users spend in different training environments, identify scenes where performance drops, or examine where users spend the most time exploring.

Event Data

Event data captures the moment-to-moment interactions that occur during a session.

These events might represent actions such as pressing a button, interacting with an object, or triggering a gameplay mechanic. Each event includes contextual information about where and when it occurred.

Because Cognitive3D analytics data often includes internal identifiers for scenes, dynamic objects, and versions, working directly with API responses can require additional lookup tables to translate those identifiers into readable names.

The Python package automatically resolves many of these identifiers into human-readable labels, making it much easier to interpret events and interactions during analysis.

By analyzing event data, teams can better understand how users interact with features inside their experiences. This can help identify commonly used interactions, detect unexpected user behavior, or evaluate how design changes affect engagement.

Because the Python package enriches events with contextual session data and readable names, analysts can begin exploring these interactions immediately.

Objective Results

Objectives allow developers and designers to track whether users successfully complete defined tasks inside an experience.

For example, an objective might represent completing a training step, interacting with a required object, or reaching a specific location in an environment.

The Python package allows analysts to retrieve objective results at multiple levels of detail. Teams can analyze high-level completion rates across versions of an experience or examine step-level performance to understand exactly where users struggle. These results can also be returned at the session-level to provide even more fine-grain information.

This type of analysis can be especially valuable in training simulations or onboarding experiences where task completion is a key metric.

Exit Poll Responses

Exit polls capture feedback from users directly within the experience.

These responses can provide valuable qualitative context alongside behavioural analytics. For example, exit polls can reveal how confident users felt after completing a training module or how satisfied they were with a particular experience.

With the Python package, exit poll responses can be retrieved alongside other analytics data, making it easier to combine behavioural insights with user feedback.

Designed for Data Analysis Workflows

Many teams working with XR analytics rely on Python for tasks such as exploratory data analysis, automated reporting, and machine learning.

The Cognitive3D Python package was designed with these workflows in mind. By returning clean DataFrames and handling API complexity internally, the package allows analysts to integrate XR analytics directly into their existing toolchains.

Instead of spending time cleaning API responses, analysts can move quickly from data retrieval to insight.

What’s Next

The Python package is now available on GitHub.

Please refer to the Documentation for further details.

As the package evolves, additional analytics endpoints and improvements will continue to expand what can be analyzed directly from Python.

For teams already working with XR analytics, the Python package provides a faster and more flexible way to explore and understand user behaviour.

---