Install & Compatibility
Where this runs
tested against v1.5.24 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.654s · 35.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.604s · 36MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
surge
✓ import surge
✗ from surge_api import SurgeClient
The top-level package is 'surge', not 'surge_api'.
surge.Project
✓ import surge
projects = surge.Project.list()
Classes like `Project` are typically accessed directly through the `surge` module.
This quickstart demonstrates how to authenticate with the Surge AI API using an environment variable and then list existing projects. It also shows how to retrieve a specific project by its ID. Remember to set the `SURGE_API_KEY` environment variable.
import surge
import os
# Set your Surge AI API key from an environment variable
surge.api_key = os.environ.get('SURGE_API_KEY', '')
if not surge.api_key:
print("Error: SURGE_API_KEY environment variable not set.")
else:
try:
# List all projects under your Surge account
projects = surge.Project.list()
if projects:
print(f"Successfully retrieved {len(projects)} projects.")
print(f"First project name: {projects[0].name}")
# Retrieve a specific project by ID (replace with a real ID if available)
# For demonstration, we'll try to retrieve the first project by its ID
project_id = projects[0].id
single_project = surge.Project.retrieve(project_id)
print(f"Retrieved project by ID: {single_project.name}")
# Example: Download results (uncomment and adjust as needed)
# results = single_project.download_json()
# print(f"Downloaded results for {single_project.name}: {results[:100]}...")
else:
print("No projects found in your Surge AI account.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe Surge API is in a pre-release state, and the developers do not guarantee full backward compatibility. While efforts are made to maintain compatibility, breaking changes may occur without major version increments.fixRefer to the official GitHub repository and any release notes or changelogs for migration guides before upgrading.
affects: All pre-release versions (potentially all versions until 1.x.x is declared stable)
gotchaThere are multiple Python packages and tools that use 'Surge' in their name (e.g., a file downloading utility, a networking proxy, an SMS API). Ensure you are installing and using `surge-api` (for Surge AI's human intelligence platform) to avoid confusion and incorrect functionality.fixAlways explicitly `pip install surge-api` and refer to the official `surge-ai/surge-python` GitHub repository for documentation.
affects: All versions
gotchaAuthentication requires a valid API key. Common errors include an invalid, missing, or improperly configured API key, leading to unauthorized access errors.fixEnsure `surge.api_key` is set with a correct key from your Surge Profile or that the `SURGE_API_KEY` environment variable is properly configured before making API calls.
affects: All versions
deprecatedThe Surge platform has renamed 'Segments' to 'Audiences' for clarity. While there were no immediate breaking changes for existing API endpoints at the time of the announcement, new 'Audience' endpoints are expected. This indicates a potential future shift in terminology or API structure.fixMonitor official Surge AI documentation and announcements for updates regarding the 'Segments' to 'Audiences' transition and new API endpoints. Adapt your code to use new 'Audience' functionality as it becomes available.
affects: All versions, particularly when dealing with 'Segments' related functionality
Upgrade
Version history
1.5.24latest on PyPI · released May 28, 2026
Audit
Dependencies
No dependency data recorded yet.