{"id":5507,"library":"surge-api","title":"Surge Python SDK","description":"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.","status":"active","version":"1.5.21","language":"en","source_language":"en","source_url":"https://github.com/surge-ai/surge-python","tags":["AI","data labeling","API client","human-in-the-loop","natural language processing"],"install":[{"cmd":"pip install --upgrade surge-api","lang":"bash","label":"Install Surge Python SDK"}],"dependencies":[],"imports":[{"note":"The top-level package is 'surge', not 'surge_api'.","wrong":"from surge_api import SurgeClient","symbol":"surge","correct":"import surge"},{"note":"Classes like `Project` are typically accessed directly through the `surge` module.","symbol":"surge.Project","correct":"import surge\nprojects = surge.Project.list()"}],"quickstart":{"code":"import surge\nimport os\n\n# Set your Surge AI API key from an environment variable\nsurge.api_key = os.environ.get('SURGE_API_KEY', '')\n\nif not surge.api_key:\n    print(\"Error: SURGE_API_KEY environment variable not set.\")\nelse:\n    try:\n        # List all projects under your Surge account\n        projects = surge.Project.list()\n        if projects:\n            print(f\"Successfully retrieved {len(projects)} projects.\")\n            print(f\"First project name: {projects[0].name}\")\n            \n            # Retrieve a specific project by ID (replace with a real ID if available)\n            # For demonstration, we'll try to retrieve the first project by its ID\n            project_id = projects[0].id\n            single_project = surge.Project.retrieve(project_id)\n            print(f\"Retrieved project by ID: {single_project.name}\")\n            \n            # Example: Download results (uncomment and adjust as needed)\n            # results = single_project.download_json()\n            # print(f\"Downloaded results for {single_project.name}: {results[:100]}...\")\n\n        else:\n            print(\"No projects found in your Surge AI account.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official GitHub repository and any release notes or changelogs for migration guides before upgrading.","message":"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.","severity":"breaking","affected_versions":"All pre-release versions (potentially all versions until 1.x.x is declared stable)"},{"fix":"Always explicitly `pip install surge-api` and refer to the official `surge-ai/surge-python` GitHub repository for documentation.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Authentication requires a valid API key. Common errors include an invalid, missing, or improperly configured API key, leading to unauthorized access errors.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions, particularly when dealing with 'Segments' related functionality"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}