Registry / http-networking / cognite-sdk

cognite-sdk

JSON →
library8.14.0pypypi✓ verified 23d ago

The Cognite Python SDK is a client library for interacting with Cognite Data Fusion (CDF), a cloud-based industrial data platform. It simplifies programmatic access to CDF's APIs, enabling developers and data scientists to work efficiently with industrial data. The package is tightly integrated with pandas, facilitating data manipulation. The current version is 8.0.7, and major versions are released periodically, introducing significant new features like full asynchronous support in v8.

pip install cognite-sdk
INSTALL
IMPORT
SIG · COGNITE-SDK
C
cognite-sdk
http-networkingpythonv8.14.0
Install
9.2s avg
Import
1949ms
Disk
58MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v8.14.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
1/2 runs
✓ 9.7s
py 3.11
1/2 runs
✓ 9.05s
py 3.12
1/2 runs
✓ 8.6s
py 3.13
1/2 runs
✓ 8.4s
py 3.9
1/2 runs
✓ 10.25s
58MB installed
● package 58MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CogniteClient
from cognite.client import CogniteClient
The synchronous client, still fully supported and wraps the AsyncCogniteClient internally in v8.
AsyncCogniteClient
from cognite.client import AsyncCogniteClient
The new primary asynchronous client introduced in v8.
ClientConfig
from cognite.client import ClientConfig
Used for configuring the client instance.
OAuthClientCredentials
from cognite.client.credentials import OAuthClientCredentials
A common credential provider for OAuth2 client credentials flow.
Internal Modules
from cognite.client import SomeClass
from cognite.client.data_classes._some_internal_module import SomeClass
Avoid importing from internal SDK modules (prefixed with `_`) as their structure may change, leading to compatibility issues. All public interfaces should be imported from the top level `cognite.client` package.

This quickstart demonstrates how to instantiate both the synchronous (`CogniteClient`) and asynchronous (`AsyncCogniteClient`) clients for Cognite Data Fusion, emphasizing the recommended use of environment variables for secure credential handling via `OAuthClientCredentials` and `ClientConfig`. The `AsyncCogniteClient` is new in v8 and is now the primary client.

import os from cognite.client import CogniteClient, AsyncCogniteClient, ClientConfig, global_config from cognite.client.credentials import OAuthClientCredentials import asyncio # It is highly recommended to use environment variables for sensitive information. # Example environment variables: # COGNITE_TENANT_ID='YOUR_TENANT_ID' # COGNITE_CLIENT_ID='YOUR_CLIENT_ID' # COGNITE_CLIENT_SECRET='YOUR_CLIENT_SECRET' # COGNITE_CLUSTER='westeurope-1' # COGNITE_PROJECT='my-cdf-project' # COGNITE_CLIENT_NAME='my-python-app' # 1. Configure the client using environment variables tenant_id = os.environ.get('COGNITE_TENANT_ID', 'your-tenant-id') client_id = os.environ.get('COGNITE_CLIENT_ID', 'your-client-id') client_secret = os.environ.get('COGNITE_CLIENT_SECRET', 'your-client-secret') cluster = os.environ.get('COGNITE_CLUSTER', 'api') # e.g., 'westeurope-1' for 'https://westeurope-1.cognitedata.com' project = os.environ.get('COGNITE_PROJECT', 'my-cdf-project') client_name = os.environ.get('COGNITE_CLIENT_NAME', 'my-python-app') base_url = f"https://{cluster}.cognitedata.com" creds = OAuthClientCredentials( token_url=f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token", client_id=client_id, client_secret=client_secret, scopes=[f"{base_url}/.default"] ) client_config = ClientConfig( client_name=client_name, base_url=base_url, project=project, credentials=creds ) # Optionally set a global configuration (will be used if no config is explicitly passed) global_config.default_client_config = client_config # 2. Instantiate a synchronous client (still supported in v8) sync_client = CogniteClient() print(f"Synchronous client initialized for project: {sync_client.config.project}") # Example usage: # assets = sync_client.assets.list(limit=1) # if assets: print(f"Found asset: {assets[0].name}") # 3. Instantiate an asynchronous client (new and recommended in v8) async def main(): async_client = AsyncCogniteClient() print(f"Asynchronous client initialized for project: {async_client.config.project}") # Example usage: # tss = await async_client.time_series.list(limit=1) # if tss: print(f"Found time series: {tss[0].name}") await async_client.close() if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingMajor architectural shift to full asynchronous support in v8. The new `AsyncCogniteClient` is the primary client, and the synchronous `CogniteClient` now internally wraps the async client. This also introduces `httpx` as a new required dependency.
fix
Migrate to `AsyncCogniteClient` for native async/await patterns. If continuing to use `CogniteClient`, be aware it's now an async wrapper. Ensure `httpx` is installed. Review helper/utility methods, as many now have `_async` variants (e.g., `asset.children_async()`).
affects: 8.x.x (from 7.x.x)
breakingRemoved deprecated API accessors. `client.datapoints` and `client.extraction_pipeline_runs` attributes are no longer available.
fix
Replace `client.datapoints` with `client.time_series.data`. Replace `client.extraction_pipeline_runs` with `client.extraction_pipelines.runs`.
affects: 8.x.x (from 7.x.x)
breakingGeneric `aggregate` and `filter` methods on classic CDF APIs (Assets, Events, Sequences, TimeSeries) have been removed or replaced with more specific alternatives.
fix
Use specific aggregation methods like `aggregate_count`, `aggregate_unique_values`, etc. For filtering, use the `list` method with `advanced_filters` instead of the generic `filter` method.
affects: 8.x.x (from 7.x.x)
breakingThe static method `NodeId.load_if()` was removed. Attempting to call it will result in an `AttributeError`.
fix
This method was likely an internal implementation detail and has been removed in v8. If you relied on this, you may need to re-evaluate your approach or use the (potentially internal) `_load_if` if absolutely necessary, but this is not recommended.
affects: 8.x.x (from 7.x.x)
gotchaHardcoding credentials (API keys, client secrets) is a security risk.
fix
Always use environment variables, a secure configuration file, or a credential provider that fetches tokens securely (e.g., `OAuthClientCredentials` as shown in quickstart).
affects: All versions
gotchaImporting from internal SDK modules (e.g., `cognite.client.data_classes._some_module`) can lead to breaking changes.
fix
Only import symbols directly from `cognite.client` or other documented top-level modules. Internal module structures are not part of the public API and can change without warning between versions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cognite.client'
The Python package for the Cognite SDK is named `cognite-sdk` on PyPI, so attempting to import from a module named `cognite.client` without having installed the correct package will result in this error.
fix
Install the correct package using `pip install cognite-sdk`.
Could not fetch a valid token or a valid API key. Unable to instantiate a CogniteClient. Please verify your credentials.
The CogniteClient failed to authenticate because it could not find valid credentials (API key or OIDC token) or the configured project/base URL was incorrect.
fix
Ensure environment variables like `COGNITE_API_KEY`, `COGNITE_CLIENT_ID`, `COGNITE_CLIENT_SECRET`, `COGNITE_TOKEN_URL`, `COGNITE_PROJECT`, and `COGNITE_BASE_URL` are correctly set, or pass these parameters directly when instantiating `CogniteClient` or `ClientConfig`.
AttributeError: 'CogniteClient' object has no attribute 'datapoints'
The `datapoints` accessor on the `CogniteClient` object was deprecated and replaced with `time_series` in newer versions of the SDK.
fix
Update your code to use `client.time_series` instead of `client.datapoints`.
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED]
Python's SSL certificate verification failed when trying to establish a secure connection to the Cognite Data Fusion API, often due to network configurations (e.g., corporate proxies) or an outdated `certifi` package.
fix
Update your `certifi` package (`pip install --upgrade certifi`), ensure your system's certificate store is correctly configured, or, for development purposes, disable SSL verification by setting `disable_ssl=True` in your `ClientConfig` (not recommended for production).
CogniteAPIError: ... code: 403
A `CogniteAPIError` with status code 403 indicates that the authenticated user or service account lacks the necessary capabilities (permissions) in Cognite Data Fusion to perform the requested operation.
fix
Verify that the API key or OIDC token used for authentication is associated with a service account that has the required access rights in CDF for the specific resource and action being attempted.
Upgrade
Version history
8.14.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
httpxrequiredNew required dependency since v8, replaces 'requests' for HTTP operations and enables async functionality.
pandasoptionalFor enhanced DataFrame integration, available via 'cognite-sdk[pandas]' extra.
geopandasoptionalFor geospatial data handling, available via 'cognite-sdk[geo]' extra.
Agent activity
24 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources
cognite-sdk — pip install cognite-sdk · libregistry