Client

The Labelbox Client is essential for all SDK workflows. It connects to a Labelbox server with your authentication API key and provides functions for querying and creating data assets.

Instantiate Labelbox Client

Your Client is associated with the API key of your account. See more in Create an API key.

import labelbox as lb

## Option 1: List API_KEY in your Python script
API_KEY = "<YOUR_API_KEY>"
client = lb.Client(api_key=API_KEY)

## Option 2: Pass your API key as an environment variable $LABELBOX_API_KEY
# In your terminal:
user@machine:~$ export LABELBOX_API_KEY="<YOUR_API_KEY>"
# In Python:
client = lb.Client()

Create, modify, and query assets

Using the Client interface, you can create, modify, and query high-level data assets - Dataset, Project, Ontology, and Model. For details, please refer to the documentation linked in each of these modules.

Dataset

Create a dataset

The only required argument when creating a dataset is the name.

dataset = client.create_dataset(
  name='<dataset_name>',
  description='<dataset_description>',	# optional
  iam_integration=None		# if not specified, will use default integration, set as None to not use delegated access.
)

Get a dataset

dataset = client.get_dataset("<dataset_id>")

datasets = client.get_datasets(
  where=(Dataset.name == "<dataset_name>") & (Dataset.description == "<dataset_description>")
)

Data row

Get a data row

data_row = client.get_data_row("<data_row_id>")

data_row = client.get_data_row_by_global_key("key1")

data_row_ids = get_data_row_ids_for_global_keys(["key1", "key2"])

Assign global keys to data rows

global_key_data_row_inputs = [
  {"data_row_id": "<data_row_id>", "global_key": "key1"},
  {"data_row_id": "<data_row_id>", "global_key": "key2"}
]

client.assign_global_keys_to_data_rows(global_key_data_row_inputs)

Clear global keys

client.clear_global_keys(["key1", "key2"])

Project

Create a project

project = client.create_project(
    name="<project_name>",
    description="<project_description>",	# optional
    media_type=lb.MediaType.Image			# must specify the media type
)

Get a project

project = client.get_project("<project_id>")

projects = client.get_projects(
  where=(Project.name == "<project_name>") & (Project.description == "<project_description>")
)

Feature

Create a feature

# Create a tool
feature_schema = client.create_feature_schema(
  normalized={
    'tool': 'polygon',  
    'name': 'cat', 
    'color': 'black'
  }
)

Get a feature

Note: This will return all feature schemas if name name_contains="" or name_contains=None

feature_schema = client.get_feature_schema("<feature_schema_id>")
feature_schemas = client.get_feature_schemas(name_contains="<keyword>")

Update feature title

client.update_feature_schema_title("<feature_schema_id>", "new_title")

Get unused features

client.get_unused_feature_schemas()

Delete an unused feature

client.delete_unused_feature_schema("<feature_schema_id>")

Ontology

Create an ontology

# Create an ontology (option 1)
# Note that to use this option, you must create a Feature object as shown above
ontology = client.create_ontology_from_feature_schemas(
  name="<ontology_name>",
  media_type=lb.MediaType.Image,
  feature_schema_ids=[feature_schema.uid]
)

# Create an ontology (option 2)
ontology = client.create_ontology(
  name="<ontology_name>",
  media_type=lb.MediaType.Image,
  normalized={
    "tools": [{'tool': 'polygon',  'name': 'cat', 'color': 'black'}],
    "classifications": []
  }
)

Insert feature into an existing ontology

client.insert_feature_schema_into_ontology(
    feature_schema_id="<feature_schema_id>",
    ontology_id="<ontology_id>",
    position=4
)

Check if a feature is archived in an ontology

client.is_feature_schema_archived("<ontology_id>", "<feature_schema_id>")

Get an ontology

ontology = client.get_ontology("<ontology_id>")
ontologies = client.get_ontologies(name_contains="<keyword>")

Get unused ontologies

client.get_unused_ontologies()

Delete an unused ontology

client.delete_unused_ontology("<ontology_id>")

Model

Create a model

model = client.create_model(
  name="<model_name>",
  ontology_id="<ontology_id>"
)

Get a model

model = client.get_model("<model_id>")
models = client.get_models(where=(Model.name == "<model_name>"))

Model run

Get a model run

model_run = client.get_model_run("<model_run_id>")

Get a model slice

model_slice = client.get_model_slice("<model_slice_id>")

Catalog slice

Get a Catalog slice

catalog_slice = client.get_catalog_slice("<catalog_slice_id>")

Metadata

Get the metadata ontology

metadata_ontology = client.get_data_row_metadata_ontology()

User

Get the current user

user = client.get_user()

Organization

Get the current organization

organization = client.get_organization()

Get the available roles

roles = client.get_roles()