Surge Python SDK

1.5.21 · active · verified Mon Apr 13

The Surge Python SDK (current version 1.5.21) provides convenient access to the Surge AI API, enabling applications to interact with the Surge AI platform for data annotation, human intelligence tasks, and managing projects. It is actively maintained with regular updates.

Warnings

breaking The 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.
Fix: Refer to the official GitHub repository and any release notes or changelogs for migration guides before upgrading.
gotcha There 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.
Fix: Always explicitly `pip install surge-api` and refer to the official `surge-ai/surge-python` GitHub repository for documentation.
gotcha Authentication requires a valid API key. Common errors include an invalid, missing, or improperly configured API key, leading to unauthorized access errors.
Fix: Ensure `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.
deprecated The 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.
Fix: Monitor 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.

Install

pip install --upgrade surge-api Install Surge Python SDK

Imports

surge
```
import surge
```
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.

Quickstart

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}")

view raw JSON →