Enabling the alpha API Subversion and DEBUG mode in the Cognite Python SDK [Cognite Official]

Overview

Cognite Data Fusion (CDF) evolves continuously, and some capabilities are first exposed through experimental (alpha) API subversions before becoming part of the stable v1 API. These alpha endpoints are primarily intended for:

• Testing new or unreleased CDF features

• Investigating Data Modeling Service (DMS) behavior

• Debugging query execution plans and backend behavior

• Reproducing issues together with Cognite Support or Engineering

To support these workflows, the Cognite Python SDK provides:

• A debug flag to enable detailed HTTP-level logging

However, not all configuration parameters behave the same way.
Some can be safely modified after client initialization, while others must be defined at initialization time to guarantee correct and consistent behavior—especially across different execution environments such as CDF-hosted Jupyter notebooks and local development (VS Code, scripts, CI/CD).

This document explains what can be changed, when, where, and why.

1. Environment Differences

2. Recommended Usage 

✅ Option 1: Configure During Initialization (Recommended Everywhere)

from cognite.client import CogniteClient
from cognite.client.config import ClientConfig
from cognite.client.credentials import OAuthClientCredentials

# Define OAuth credentials
creds = OAuthClientCredentials(
    token_url="https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token",
    client_id="<client_id>",
    client_secret="<client_secret>",
    scopes=["https://<cluster>.cognitedata.com/.default"]
)

# Create client configuration with alpha API subversion
cnf = ClientConfig(
    client_name="my-special-client",
    base_url="https://<cluster>.cognitedata.com",
    project="<project_name>",
    credentials=creds,
    debug=True,                  # Enable SDK debug mode
    api_subversion="alpha"       # Use alpha API endpoints
)

# Initialize the Cognite client
client = CogniteClient(cnf)

✔ This is the recommended and fully supported method.

• All SDK services behave uniformly

• Safe across SDK upgrades and long-running processes

✅ Option 2: Modify After Initialization (CDF Jupyter Only)

CDF-hosted Jupyter notebooks support limited post-initialization configuration changes for interactive debugging.

from cognite.client import CogniteClient

# Initialize with auto-injected credentials (works only in CDF-hosted notebooks)
client = CogniteClient()

# Enable alpha mode and debugging
client.config.api_subversion = "alpha"
client.config.client_name = "my-special-client"
client.config.debug = True

✔ This approach works in CDF Jupyter because it uses pre-injected credentials
and a mutable configuration object that all services reference directly.

3. Enabling SDK Debug Logging

The debug flag enables low-level HTTP tracing, which is invaluable when troubleshooting or validating request behavior.

What debug mode provides

With debug=True, the SDK logs:

• Full request URLs (confirming /api/v1/ vs /api/alpha/)

• Request payloads

• Request and response headers

• Response payloads

• Timing information

• x-request-id for backend correlation

Example output:

HTTP/1.1 POST https://<cluster>.cognitedata.com/api/v1/projects/<project_name>/assets/list 200
- payload: {'limit': 1}
- headers: {... 'x-cdp-sdk': 'CognitePythonSDK:X.XX.0', 'x-cdp-app': 'XXXX', 'cdf-version': 'alpha'}
- response_headers: {'x-request-id': '...'}

How to enable debug logging

Option A: During Initialization (Recommended)

cnf = ClientConfig(
    client_name="my-special-client",
    base_url="https://<cluster>.cognitedata.com",
    project="<project_name>",
    credentials=creds,
    debug=True,  # Enables verbose debug logging
    api_subversion="alpha"
)

client = CogniteClient(cnf)

Option B: After Initialization

client = CogniteClient()
client.config.debug = True

When debug=True, SDK logs include:

• Header confirming 'cdf-version': 'alpha' usage)

• Request headers and response codes

• Timing information for each API call

These details appear directly in your notebook or terminal output.

4. Important Notes

• Setting client.config.api_subversion = "alpha" after initialization works only in CDF-managed Jupyter environments.

• client.config.debug = True can be enabled anytime and is safe everywhere.

• For scripts or applications running outside CDF, please configure via ClientConfig(...) at initialization time.

• The alpha APIs are experimental and may change or be deprecated without notice.

• Use client.config.debug = True only when actively troubleshooting. It can produce verbose logs.