Python Domino API Client

2.1.0 · active · verified Fri Apr 17

The `dominodatalab` library provides official Python bindings for the Domino Data Lab API, enabling programmatic interaction with Domino projects, jobs, models, and environments. As of version 2.1.0, it supports advanced features like agentic workflow tracing and enhanced job control. The library maintains an active release cadence, with major updates and minor patches released regularly.

Common errors

```
ModuleNotFoundError: No module named 'domino.aisystems'
```
cause Attempting to import from the old `domino.aisystems` module after upgrading to `dominodatalab` version 2.0.0 or newer.

fix Update your import statements from `from domino.aisystems import ...` to `from domino.agents import ...`.
```
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...
```
cause The provided `DOMINO_USER_API_KEY` is either incorrect, expired, or does not have sufficient permissions for the requested operation.

fix Verify your `DOMINO_USER_API_KEY` in the Domino UI and ensure it matches the environment variable. Check if the key has the necessary permissions (e.g., project access, API access).
```
requests.exceptions.HTTPError: 404 Client Error: Not Found for url: ...
```
cause The specified `DOMINO_API_HOST`, `DOMINO_PROJECT_OWNER`, or `DOMINO_PROJECT_NAME` is incorrect, leading the API client to request a non-existent resource.

fix Double-check the `DOMINO_API_HOST` URL, and confirm the exact spelling and case for `DOMINO_PROJECT_OWNER` and `DOMINO_PROJECT_NAME` as they appear in Domino Data Lab.
```
TypeError: 'NoneType' object is not callable (or similar error during client initialization)
```
cause One or more required environment variables (e.g., `DOMINO_API_HOST`, `DOMINO_USER_API_KEY`) were not set, resulting in `None` being passed to the `Domino` client constructor, leading to subsequent errors when trying to use `None` as a string.

fix Ensure all necessary environment variables are properly defined and accessible before initializing the `Domino` client. Print `os.environ.get('VAR_NAME')` to confirm their values.

Warnings

breaking The `domino.aisystems` module was renamed to `domino.agents` in version 2.0.0. Code using `domino.aisystems` imports or functionality will break.
Fix: Update all import statements and references from `domino.aisystems` to `domino.agents`.
gotcha Incorrect or missing API credentials (host, API key, project owner, project name) are the most common cause of client initialization failures or HTTP errors (e.g., 401 Unauthorized, 404 Not Found).
Fix: Verify that `DOMINO_API_HOST`, `DOMINO_USER_API_KEY`, `DOMINO_PROJECT_OWNER`, and `DOMINO_PROJECT_NAME` environment variables are correctly set and accessible to your Python process.
gotcha The library has historically pinned specific versions of dependencies like `typing-extensions` and `mlflow`. While `typing-extensions` constraints were relaxed in 2.1.0 for Python 3.10+, older versions or specific environments might still encounter dependency conflicts with other libraries.
Fix: If encountering dependency conflicts, try upgrading to the latest `dominodatalab` version. If the issue persists, consider isolating the environment (e.g., using `venv` or Docker) or carefully reviewing dependency trees with `pip check` or `pipdeptree`.

Install

pip install dominodatalab Install latest version

Imports

Domino
wrong:
```
from dominodatalab import Domino
```
correct:
```
from domino import Domino
```
The top-level package name on PyPI is 'dominodatalab', but the primary module for import is 'domino'.

DominoAgentContext

wrong:

from domino.aisystems.logging import DominoAgentContext

correct:

from domino.agents.logging import DominoAgentContext

The 'aisystems' module was renamed to 'agents' in version 2.0.0.

Quickstart

Initializes the Domino client using environment variables for host, API key, project owner, and project name, then attempts to list projects as a basic connectivity test. This pattern is recommended for secure credential management.

import os
from domino import Domino

# Configure environment variables (replace with your actual values or ensure they are set)
# DOMINO_API_HOST: e.g., 'https://your.domino.url'
# DOMINO_USER_API_KEY: Your Domino API key
# DOMINO_PROJECT_OWNER: The username of the project owner
# DOMINO_PROJECT_NAME: The name of the project

domino = Domino(
    host=os.environ.get("DOMINO_API_HOST", ""),
    api_key=os.environ.get("DOMINO_USER_API_KEY", ""),
    project_owner=os.environ.get("DOMINO_PROJECT_OWNER", ""),
    project_name=os.environ.get("DOMINO_PROJECT_NAME", "")
)

# Example: List projects accessible by the user
try:
    # Ensure required environment variables are set
    if not all([domino.host, domino.api_key, domino.project_owner, domino.project_name]):
        raise ValueError("Missing one or more required environment variables for Domino API access.")

    print(f"Attempting to connect to Domino at {domino.host}...")
    projects = domino.projects_list()
    print(f"Successfully connected. Found {len(projects)} projects accessible by user: {domino.project_owner}.")
    if projects:
        print(f"First project: {projects[0].name}")
except Exception as e:
    print(f"Error connecting to Domino or listing projects: {e}")
    print("Please ensure DOMINO_API_HOST, DOMINO_USER_API_KEY, DOMINO_PROJECT_OWNER, DOMINO_PROJECT_NAME are correctly set.")

view raw JSON →