Surge Python SDK

The Surge Python SDK provides convenient access to the Surge API from applications written in the Python language.

Installation

Install this package by using pip:

pip install --upgrade surge-api

Requirements

Python 3.10+

Usage

Documentation and examples are available here.

Authentication

The library needs to be configured with your account's API key which is available in your Surge Profile. Set surge.api_key to its value:

import surge
surge.api_key = "YOUR API KEY"

Or set the API key as an environment variable:

export SURGE_API_KEY=<YOUR API KEY>

Downloading project results

Once the API key has been set, you can list all of the Projects under your Surge account or retrieve a specific Project by its ID.

# List your Projects
projects = surge.Project.list()

# Print the name of the first Project
print(projects[0].name)

# Retrieve a specific Project
project = surge.Project.retrieve("076d207b-c207-41ca-b73a-5822fe2248ab")

# Download the results for that project
results = project.download_json()

# Alternatively, download the results to a file
project.save_report("export_csv", "results.csv")

Creating projects

If you have a blueprint, you can use it as a template to get a new batch of data annotated. You can add new labeling tasks from a CSV or with a list of dictionaries.

# List blueprint projects
blueprint_projects = surge.Project.list_blueprints()
blueprint = blueprint_projects[0]

# Create a project from a blueprint
project = surge.Project.create("My Labeling Project (July 2023 Batch)", template_id=blueprint.id)

# Add data from a CSV file
project.create_tasks_from_csv('my_data.csv')

# Or add data directly
tasks = project.create_tasks([{
    "company": "Surge",
    "city": "San Francisco",
    "state": "CA"
}])

Creating tasks

You can create new Tasks for a project, list all of the Tasks in a given project, or retrieve a specific Task given its ID.

# Create Tasks for the new Project
tasks_data = [{"id": 1, "company": "Surge AI"}, {"id": 2, "company":"Twitch TV"}]
tasks = project.create_tasks(tasks_data)

# List all Tasks in the Project
all_tasks = project.list_tasks()

# Retrieve a specific Task
task = surge.Task.retrieve(task_id = "eaa44610-c8f6-4480-b746-28b6c8defd4d")

# Print the fields of that Task
print(task.fields)

You can also create Tasks in bulk by uploading a local CSV file. The header of the CSV file must specify the fields that are used in your Tasks.

id	company
1	Surge AI
2	Twitch TV

# Create Tasks in bulk via CSV file
file_path = "./companies_to_classify.csv"
tasks = project.create_tasks_from_csv(file_path)

Development

The test suite depends on pytest, which you can install using pip:

pip install pytest

To run tests from the command line:

# Run all tests
pytest

# Run tests in a specific file
pytest tests/test_projects.py

# Run a specific test
pytest tests/test_projects.py::test_init_complete

Metadata

Release files for surge-api 1.5.24

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for surge-api 1.5.24
File	Interpreter	ABI	Platform	Reset
surge_api-1.5.24-py3-none-any.whl 22.4 kB May 28, 2026	Python 3	none	any	Details

Release files / surge_api-1.5.24-py3-none-any.whl

Download URL	surge_api-1.5.24-py3-none-any.whl
Size	22.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d3eb6d19c50352ff48f6b8c03e387d8de1d1c7b9a8fdb594baeff80288dc07cb`
BLAKE2b-256 checksum How to use checksums	`6b60550e578bbd6173f5a109bc1f653c96ba2eb6d5fe5e6a761c8c969cee22be`
Upload date	May 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.5`