CogniteClient

The SDK provides two client classes:

  • AsyncCogniteClient - The primary async client using native async/await patterns (new in v8)

  • CogniteClient - The synchronous client for backward compatibility (wraps the async client internally)

Both clients share the same configuration via ClientConfig.

AsyncCogniteClient

class cognite.client.AsyncCogniteClient(config: ClientConfig | None = None)

Main entrypoint into the Cognite Python SDK.

All Cognite Data Fusion APIs are accessible through this asynchronous client. For the synchronous client, see CogniteClient.

Parameters:

config (ClientConfig | None) – The configuration for this client.

async get(
url: str,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → CogniteHTTPResponse

Perform a GET request to an arbitrary path in the API.

async post(
url: str,
json: dict[str, Any] | None = None,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → CogniteHTTPResponse

Perform a POST request to an arbitrary path in the API.

async put(
url: str,
json: dict[str, Any] | None = None,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → CogniteHTTPResponse

Perform a PUT request to an arbitrary path in the API.

property version: str

Returns the current SDK version.

Returns:

The current SDK version

Return type:

str

property config: ClientConfig

Returns a config object containing the configuration for the current client.

Returns:

The configuration object.

Return type:

ClientConfig

classmethod default(
project: str,
cdf_cluster: str,
credentials: CredentialProvider,
client_name: str | None = None,
) → AsyncCogniteClient

Create an AsyncCogniteClient with default configuration.

The default configuration creates the URLs based on the project and cluster:

  • Base URL: “https://{cdf_cluster}.cognitedata.com/

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

An AsyncCogniteClient instance with default configurations.

Return type:

AsyncCogniteClient

classmethod default_oauth_client_credentials(
project: str,
cdf_cluster: str,
tenant_id: str,
client_id: str,
client_secret: str,
client_name: str | None = None,
) → AsyncCogniteClient

Create an AsyncCogniteClient with default configuration using a client credentials flow.

The default configuration creates the URLs based on the project and cluster:

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • tenant_id (str) – The Azure tenant ID.

  • client_id (str) – The Azure client ID.

  • client_secret (str) – The Azure client secret.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

An AsyncCogniteClient instance with default configurations.

Return type:

AsyncCogniteClient

classmethod default_oauth_interactive(
project: str,
cdf_cluster: str,
tenant_id: str,
client_id: str,
client_name: str | None = None,
) → AsyncCogniteClient

Create an AsyncCogniteClient with default configuration using the interactive flow.

The default configuration creates the URLs based on the tenant_id and cluster:

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • tenant_id (str) – The Azure tenant ID.

  • client_id (str) – The Azure client ID.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

An AsyncCogniteClient instance with default configurations.

Return type:

AsyncCogniteClient

classmethod load(
config: dict[str, Any] | str,
) → AsyncCogniteClient

Load a cognite client object from a YAML/JSON string or dict.

Parameters:

config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the AsyncCogniteClient class.

Returns:

A cognite client object.

Return type:

AsyncCogniteClient

Examples

Create a cognite client object from a dictionary input:

>>> from cognite.client import AsyncCogniteClient
>>> import os
>>> config = {
...     "client_name": "abcd",
...     "project": "cdf-project",
...     "base_url": "https://api.cognitedata.com/",
...     "credentials": {
...         "client_credentials": {
...             "client_id": "abcd",
...             "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...             "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...             "scopes": ["https://api.cognitedata.com/.default"],
...         },
...     },
... }
>>> client = AsyncCogniteClient.load(config)

CogniteClient (sync)

class cognite.client.CogniteClient(config: ClientConfig | None = None)

Main entrypoint into the Cognite Python SDK.

All Cognite Data Fusion APIs are accessible through this synchronous client. For the asynchronous client, see AsyncCogniteClient.

Parameters:

config (ClientConfig | None) – The configuration for this client.

get(
url: str,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → CogniteHTTPResponse

Perform a GET request to an arbitrary path in the API.

post(
url: str,
json: dict[str, Any] | None = None,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → CogniteHTTPResponse

Perform a POST request to an arbitrary path in the API.

put(
url: str,
json: dict[str, Any] | None = None,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → CogniteHTTPResponse

Perform a PUT request to an arbitrary path in the API.

property version: str

Returns the current SDK version.

Returns:

The current SDK version

Return type:

str

property config: ClientConfig

Returns a config object containing the configuration for the current client.

Returns:

The configuration object.

Return type:

ClientConfig

classmethod default(
project: str,
cdf_cluster: str,
credentials: CredentialProvider,
client_name: str | None = None,
) → CogniteClient

Create an CogniteClient with default configuration.

The default configuration creates the URLs based on the project and cluster:

  • Base URL: “https://{cdf_cluster}.cognitedata.com/

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

An CogniteClient instance with default configurations.

Return type:

CogniteClient

classmethod default_oauth_client_credentials(
project: str,
cdf_cluster: str,
tenant_id: str,
client_id: str,
client_secret: str,
client_name: str | None = None,
) → CogniteClient

Create an CogniteClient with default configuration using a client credentials flow.

The default configuration creates the URLs based on the project and cluster:

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • tenant_id (str) – The Azure tenant ID.

  • client_id (str) – The Azure client ID.

  • client_secret (str) – The Azure client secret.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

An CogniteClient instance with default configurations.

Return type:

CogniteClient

classmethod default_oauth_interactive(
project: str,
cdf_cluster: str,
tenant_id: str,
client_id: str,
client_name: str | None = None,
) → CogniteClient

Create an CogniteClient with default configuration using the interactive flow.

The default configuration creates the URLs based on the tenant_id and cluster:

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • tenant_id (str) – The Azure tenant ID.

  • client_id (str) – The Azure client ID.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

An CogniteClient instance with default configurations.

Return type:

CogniteClient

classmethod load(
config: dict[str, Any] | str,
) → CogniteClient

Load a cognite client object from a YAML/JSON string or dict.

Parameters:

config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the CogniteClient class.

Returns:

A cognite client object.

Return type:

CogniteClient

Examples

Create a cognite client object from a dictionary input:

>>> from cognite.client import CogniteClient
>>> import os
>>> config = {
...     "client_name": "abcd",
...     "project": "cdf-project",
...     "base_url": "https://api.cognitedata.com/",
...     "credentials": {
...         "client_credentials": {
...             "client_id": "abcd",
...             "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...             "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...             "scopes": ["https://api.cognitedata.com/.default"],
...         },
...     },
... }
>>> client = CogniteClient.load(config)
class cognite.client.config.ClientConfig(
client_name: str,
project: str,
credentials: CredentialProvider,
api_subversion: str | None = None,
base_url: str | None = None,
cluster: str | None = None,
headers: dict[str, str] | None = None,
timeout: int | None = None,
file_transfer_timeout: int | None = None,
debug: bool = False,
)

Configuration object for the client

Parameters:

  • client_name (str) – A user-defined name for the client. Used to identify number of unique applications/scripts running on top of CDF.

  • project (str) – CDF Project name.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • api_subversion (str | None) – API subversion

  • base_url (str | None) – Base url to send requests to. Typically on the form ‘https://<cluster>.cognitedata.com’. Either base_url or cluster must be provided.

  • cluster (str | None) – The cluster where the CDF project is located. When passed, it is assumed that the base URL can be constructed as: ‘https://<cluster>.cognitedata.com’. Either base_url or cluster must be provided.

  • headers (dict[str, str] | None) – Additional headers to add to all requests.

  • timeout (int | None) – Timeout on requests sent to the api. Defaults to 60 seconds.

  • file_transfer_timeout (int | None) – Timeout on file upload/download requests. Defaults to 600 seconds.

  • debug (bool) – Enables debug logging to stderr. This includes full request/response details and logs regarding retry attempts (e.g., on 429 throttling or 5xx errors).

classmethod default(
project: str,
cdf_cluster: str,
credentials: CredentialProvider,
client_name: str | None = None,
) → ClientConfig

Create a default client config object.

Parameters:

  • project (str) – CDF Project name.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

A default client config object.

Return type:

ClientConfig

classmethod load(
config: dict[str, Any] | str,
) → ClientConfig

Load a client config object from a YAML/JSON string or dict.

Parameters:

config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the ClientConfig class.

Returns:

A client config object.

Return type:

ClientConfig

Examples

Create a client config object from a dictionary input:

>>> from cognite.client.config import ClientConfig
>>> import os
>>> config = {
...     "client_name": "abcd",
...     "project": "cdf-project",
...     "base_url": "https://api.cognitedata.com",
...     "credentials": {
...         "client_credentials": {
...             "client_id": "abcd",
...             "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...             "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...             "scopes": ["https://api.cognitedata.com/.default"],
...         },
...     },
... }
>>> client_config = ClientConfig.load(config)
class cognite.client.config.GlobalConfig

Global configuration object

default_client_config

A default instance of a client configuration. This will be used by the AsyncCogniteClient or CogniteClient constructor if no config is passed directly. Defaults to None.

Type:

Optional[ClientConfig]

disable_gzip

Whether or not to disable gzipping of json bodies. Defaults to False.

Type:

bool

disable_pypi_version_check

Whether or not to check for newer SDK versions when instantiating a new client. Defaults to False.

Type:

bool

status_forcelist

HTTP status codes to retry. Defaults to {429, 502, 503, 504}

Type:

Set[int]

max_retries

Max number of retries on a given http request. Defaults to 10.

Type:

int

max_retries_connect

Max number of retries on connection errors. Defaults to 3.

Type:

int

max_retry_backoff

Retry strategy employs exponential backoff. This parameter sets a max on the amount of backoff after any request failure. Defaults to 60.

Type:

int

max_connection_pool_size

The maximum number of connections which will be kept in the SDKs connection pool. Defaults to 20.

Type:

int

disable_ssl

Whether or not to disable SSL. Defaults to False

Type:

bool

proxy

Route all traffic (HTTP and HTTPS) via this proxy, e.g. “http://localhost:8030”. For proxy authentication, embed credentials in the URL: “http://user:pass@localhost:8030”. Defaults to None (no proxy).

Type:

str | None

max_workers

DEPRECATED: Use ‘concurrency_settings’ instead. Maximum number of concurrent API calls. Defaults to 5.

Type:

int

concurrency_settings

Settings controlling the maximum number of concurrent API requests for different API categories (general, raw, data_modeling etc.). These settings are frozen after the first API request is made. See https://cognite-sdk-python.readthedocs-hosted.com/en/latest/settings.html#concurrency-settings

Type:

ConcurrencySettings

follow_redirects

Whether or not to follow redirects. Defaults to False.

Type:

bool

file_download_chunk_size

Specify the file chunk size for streaming file downloads. When not specified (default is None), the actual chunk size is determined by the underlying transport, which in turn is based on the size of the data packets being read from the network socket. The chunks will be of a variable and unpredictable size, but optimized for network efficiency (best download speed).

Type:

int | None

file_upload_chunk_size

Override the chunk size for streaming file uploads. Defaults to None, which translates to 65536 (64KiB chunks).

Type:

int | None

silence_feature_preview_warnings

Whether or not to silence warnings triggered by using alpha or beta features. Defaults to False.

Type:

bool

event_loop

Override the default event loop used by the SDK.

Type:

asyncio.AbstractEventLoop | None

apply_settings(settings: dict[str, Any] | str) → None

Apply settings to the global configuration object from a YAML/JSON string or dict.

Note

All settings in the dictionary will be applied unless an invalid key is provided, a ValueError will instead be raised and no settings will be applied.

Warning

This must be done before instantiating an AsyncCogniteClient for the configuration to take effect.

Parameters:

settings (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the GlobalConfig class.

Examples

Apply settings to the global_config from a dictionary input:

>>> from cognite.client import global_config
>>> settings = {
...     "max_retries": 5,
...     "disable_ssl": True,
... }
>>> global_config.apply_settings(settings)