Civis API Python Client

2.8.1 · active · verified Thu Apr 16

The Civis API Python Client provides a convenient way to interact with the Civis Platform API from Python. It allows users to manage data, jobs, scripts, and other resources within the platform. The current version is 2.8.1, and the library maintains an active release cadence with frequent minor updates and bug fixes.

Common errors

```
civis.base.CivisAPIError: Civis API request failed with status code 401: Unauthorized
```
cause The `CIVIS_API_KEY` environment variable is either not set, incorrect, or the provided API key is invalid/expired. The client failed to authenticate with the Civis Platform.

fix Verify your `CIVIS_API_KEY` environment variable is correctly set and contains a valid Civis API key. Ensure the key has the necessary permissions for the API calls you are making.
```
ModuleNotFoundError: No module named 'civis'
```
cause The `civis` library has not been installed in your current Python environment.

fix Install the library using pip: `pip install civis`
```
AttributeError: 'PaginatedResponse' object has no attribute 'json'
```
cause You are attempting to use the `.json()` method on a `PaginatedResponse` object, but your `civis` library version is older than 2.8.0, where this method was introduced.

fix Upgrade your `civis` library to version 2.8.0 or newer: `pip install --upgrade civis`. If unable to upgrade, you will need to process the paginated response by iterating over it rather than calling `.json()`.

Warnings

gotcha Always set your Civis API key via the `CIVIS_API_KEY` environment variable. Passing the API key directly in code is less secure and not recommended for production.
Fix: Set `CIVIS_API_KEY` in your environment or use a secure secret management solution. Example: `export CIVIS_API_KEY='your_api_key'`
gotcha The `civis.io` functions (e.g., `read_civis_sql`, `read_civis`) for dataframes gained a `return_as` keyword argument in v2.6.0. While the default `"list"` maintains backward compatibility for existing code, if you explicitly want a `pandas.DataFrame` or `polars.DataFrame`, you must specify `return_as="pandas"` or `return_as="polars"`.
Fix: For DataFrame output, explicitly set `return_as="pandas"` or `return_as="polars"`: `df = civis.io.read_civis_sql(sql_query, database_id, return_as="pandas")`
gotcha The `PaginatedResponse` object gained a `.json()` method in v2.8.0. If you are on an older version and attempt to call `.json()` on a paginated response, it will result in an `AttributeError`.
Fix: Upgrade to `civis>=2.8.0` to use the `.json()` method on `PaginatedResponse` objects. Alternatively, on older versions, iterate through the response to access items.

Install

pip install civis Install stable version

Imports

APIClient
```
from civis import APIClient
```
io
wrong:
```
from civis import io
```
correct:
```
import civis.io
```
While `from civis import io` might work, `import civis.io` is the more common and recommended pattern for submodules.

Quickstart

Initialize the API client. It's recommended to set your Civis API key as an environment variable (CIVIS_API_KEY). This example attempts to list containers to verify connectivity and authentication.

import os
from civis import APIClient

# Best practice: set CIVIS_API_KEY environment variable
# If not set, you can pass it directly: APIClient(api_key="YOUR_API_KEY")
client = APIClient(api_key=os.environ.get('CIVIS_API_KEY', ''))

# Example: List containers (requires appropriate permissions)
try:
    containers = client.containers.list()
    print(f"Successfully connected! Found {len(containers)} containers.")
except Exception as e:
    print(f"Error connecting to Civis Platform: {e}")
    print("Please ensure CIVIS_API_KEY is set correctly and has permissions.")

view raw JSON →