Getting started

You can use the Label Studio Python SDK to make annotating data a more integrated part of your data science and machine learning pipelines. This software development kit (SDK) lets you call the Label Studio API directly from scripts using predefined classes and methods.

The following are basic examples. For more advanced examples, see Tutorials.

Install

Install the Label Studio SDK using pip:

pip install label-studio-sdk

or

poetry add label-studio-sdk

Authenticate and Connect to the API

“API keys” vs. “Access tokens”

In Label Studio, “access tokens” and “API keys” mean the same thing and are used interchangeably.

For example, if you set the LABEL_STUDIO_API_KEY environment variable, you will set it to your access token.

Python SDK

In your Python scripts, you will need to do the following:

• Import the SDK.

• Define your Label Studio URL.

  For example, http://localhost:8080 or https://app.humansignal.com

  Note:

  • Do not including a trailing slash in your URL
  • LABEL_STUDIO_URL should start with https:// or http://

• Define your access token/API key.

  This should be available on the Account & Settings page, but you may need to enable it at the organization level first. See Access tokens.

  You can use either the Legacy Token or the Personal Access Token, but for the SDK we recommend the Personal Access Token.

• Connect to the API.

Try this example:

1
# Define the URL where Label Studio is accessible
2
LABEL_STUDIO_URL = 'YOUR_BASE_URL'
3
# API key is available at the Account & Settings page in Label Studio UI
4
LABEL_STUDIO_API_KEY = 'YOUR_API_KEY'
5
6
# Import the SDK and the client module
7
from label_studio_sdk import LabelStudio
8
9
# Connect to the Label Studio API 
10
client = LabelStudio(base_url=LABEL_STUDIO_URL, api_key=LABEL_STUDIO_API_KEY)
11
12
# A basic request to verify connection is working
13
me = client.users.whoami()
14
15
print("username:", me.username)
16
print("email:", me.email)

$
export LABEL_STUDIO_API_KEY="YOUR_API_KEY"
$
export LABEL_STUDIO_URL="YOUR_BASE_URL"

SDK CLI

The SDK includes a CLI entrypoint that mirrors SDK resources and methods.

On leaf commands (for example projects create), use -h for minimal help (one-line summary, SDK signature, and options) and --help for the full generated documentation (parameters, examples, return shape, and options). Top-level groups only register --help.

$
export LABEL_STUDIO_API_KEY="YOUR_API_KEY"
$
export LABEL_STUDIO_URL="YOUR_BASE_URL"
$
$
# minimal help for one command
$
label-studio-sdk projects create -h
$
$
# full help (longer)
$
label-studio-sdk projects create --help
$
$
# top-level
$
label-studio-sdk --help
$
$
# List projects
$
label-studio-sdk projects list
$
$
# Create a project (generic key=value params)
$
label-studio-sdk projects create \
>
  --param title="CLI Example" \
>
  --param 'label_config=<View><Text name="text" value="$text"/></View>'

Running the CLI with uv

$
# from PyPI
$
uv run --with label_studio_sdk label-studio-sdk --help
$
$
# from github
$
uv run --with git+https://github.com/HumanSignal/label-studio-sdk.git label-studio-sdk --help
$
$
# from local
$
uv run --with-editable . label-studio-sdk --help

HTTP API

If you are calling endpoints using HTTP (such as with cUrl commands), you will need to adjust your authorization header depending on which type of access token you are using.

Personal access tokens:

$
curl -X <method> <Label Studio URL>/api/<endpoint> \
>
-H 'Authorization: Bearer <token>'

Legacy tokens:

$
curl -X <method> <Label Studio URL>/api/<endpoint> \
>
-H 'Authorization: Token <token>'

Tutorials

For examples of getting started using SDK, see the following tutorials:

• Create a Project
• Import Tasks
• Assign Users to Tasks
• Add Model Predictions
• Export and Convert Snapshots

Advanced tutorials focused on ML backends:

• Logging ML Server Predictions
• Evaluate LLM Responses
• Improve Object Detection with YOLO
• Interactive OCR with Tesseract

SDK versions and compatibility

SDK version < 1 is deprecated and no longer supported. We recommend upgrading to the latest version.

If you still want to use the older version, you can install it using pip install "label-studio-sdk<1".

You can also check out an older branch version in the GitHub repository:

1
git clone https://github.com/HumanSignal/label-studio-sdk.git
2
cd label-studio-sdk
3
git fetch origin
4
git checkout release/0.0.34

Or you can simply modify you code to change the import stream as follows:

1
from label_studio_sdk import Client
2
from label_studio_sdk.data_manager import Filters, Column, Operator, Type
3
from label_studio_sdk._legacy import Project

If you’re looking for the documentation for the older version, you can find it here.

Advanced

Handling Errors

If you encounter an error while using the Label Studio Python SDK, you can catch the error and handle it in your script.

1
from label_studio_sdk.core.api_error import ApiError
2
3
try:
4
    for annotated_task in annotated_tasks:
5
        print(annotated_task.annotations)
6
except ApiError as e:
7
    print(e)

Annotations are exported in the format specified in the Label Studio JSON format.

Timeouts

By default, requests time out after 5 seconds. You can configure this with a timeout option at the client or request level.

1
from label_studio_sdk import LabelStudio
2
3
client = LabelStudio(
4
    # All timeouts set to 20 seconds
5
    timeout=20
6
)
7
8
ls.projects.create(..., request_options={
9
    # Override timeout for a specific method
10
    'timeout_in_seconds': 20
11
})

Custom HTTP client

You can override the httpx client to customize it for your use case. Some common use cases include support for proxies and transports.

1
custom_httpx_client = httpx.Client(
2
    transport=httpx.HTTPTransport(
3
        proxy="http://my.test.proxy.example.com",
4
        local_address="0.0.0.0"
5
    )
6
)
7
client = LabelStudio(
8
    api_key="YOUR_API_KEY",
9
    base_url="YOUR_LABEL_STUDIO_URL",
10
    httpx_client=custom_httpx_client,
11
)