{"id":8012,"library":"civis","title":"Civis API Python Client","description":"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.","status":"active","version":"2.8.1","language":"en","source_language":"en","source_url":"https://github.com/civisanalytics/civis-python","tags":["api client","data platform","analytics","civis platform"],"install":[{"cmd":"pip install civis","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used by `civis.io` functions for DataFrame operations, though optional.","package":"pandas","optional":true},{"reason":"Used by `civis.io` functions for DataFrame operations as an alternative to pandas (added in v2.6.0), though optional.","package":"polars","optional":true}],"imports":[{"symbol":"APIClient","correct":"from civis import APIClient"},{"note":"While `from civis import io` might work, `import civis.io` is the more common and recommended pattern for submodules.","wrong":"from civis import io","symbol":"io","correct":"import civis.io"}],"quickstart":{"code":"import os\nfrom civis import APIClient\n\n# Best practice: set CIVIS_API_KEY environment variable\n# If not set, you can pass it directly: APIClient(api_key=\"YOUR_API_KEY\")\nclient = APIClient(api_key=os.environ.get('CIVIS_API_KEY', ''))\n\n# Example: List containers (requires appropriate permissions)\ntry:\n    containers = client.containers.list()\n    print(f\"Successfully connected! Found {len(containers)} containers.\")\nexcept Exception as e:\n    print(f\"Error connecting to Civis Platform: {e}\")\n    print(\"Please ensure CIVIS_API_KEY is set correctly and has permissions.\")","lang":"python","description":"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."},"warnings":[{"fix":"Set `CIVIS_API_KEY` in your environment or use a secure secret management solution. Example: `export CIVIS_API_KEY='your_api_key'`","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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\")`","message":"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\"`.","severity":"gotcha","affected_versions":">=2.6.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"<2.8.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"civis.base.CivisAPIError: Civis API request failed with status code 401: Unauthorized"},{"fix":"Install the library using pip: `pip install civis`","cause":"The `civis` library has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'civis'"},{"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()`.","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.","error":"AttributeError: 'PaginatedResponse' object has no attribute 'json'"}]}