API reference

Updated 2 months ago by Florijan Stamenkovic

General Classes
Data Classes
Error Classes

General classes

Client

Class labelbox.client.Client.

A Labelbox client. Contains info necessary for connecting to a Labelbox server (URL, authentication key). Provides functions for querying and creating top-level data objects (Projects, Datasets).

Object Methods

__init__(self, api_key, endpoint='https://api.labelbox.com/graphql')

Creates and initializes a Labelbox Client.

  • Args:
    • api_key (str): API key. If None, the key is obtained from the "LABELBOX_API_KEY" environment variable.
    • endpoint (str): URL of the Labelbox server to connect to.
  • Raises:

create_dataset(self, **kwargs)

Creates a Dataset object on the server. Attribute values are passed as keyword arguments:

>>> project = client.get_project("uid_of_my_project")
>>> dataset = client.create_dataset(name="MyDataset",
>>> projects=project)
  • Kwargs: Keyword arguments with new Dataset attribute values. Keys are attribute names (in Python, snake-case convention) and values are desired attribute values.
  • Returns: A new Dataset object.
  • Raises:

create_project(self, **kwargs)

Creates a Project object on the server. Attribute values are passed as keyword arguments:

>>> project = client.create_project(name="MyProject")
  • Kwargs: Keyword arguments with new Project attribute values. Keys are attribute names (in Python, snake-case convention) and values are desired attribute values.
  • Returns: A new Project object.
  • Raises:

execute(self, query, params, timeout=10.0)

Sends a request to the server for the execution of the given query. Checks the response for errors and wraps errors in appropriate labelbox.exceptions.LabelboxError subtypes.

get_dataset(self, dataset_id)

Gets a single Dataset with the given ID.

get_datasets(self, where)

Fetches all the datasets the user has access to.

  • Args:
    • where (Comparison, LogicalOperation or None): The `where` clause for filtering.
  • Returns: An iterable of Datasets (typically a PaginatedCollection).

get_labeling_frontends(self, where)

Fetches all the labeling frontends.

get_organization(self)

Gets the Organization DB object of the current user.

get_project(self, project_id)

Gets a single Project with the given ID.

get_projects(self, where)

Fetches all the projects the user has access to.

  • Args:
    • where (Comparison, LogicalOperation or None): The `where` clause for filtering.
  • Returns: An iterable of Projects (typically a PaginatedCollection).

get_user(self)

Gets the current User database object.

upload_data(self, data)

Uploads the given data (bytes) to Labelbox.

Data Classes

Project

Class labelbox.schema.project.Project (Updateable, Deletable).

A Project is a container that includes a labeling frontend, an ontology, datasets and labels.

Fields
  • auto_audit_number_of_labels (Int)
  • auto_audit_percentage (Float)
  • created_at (DateTime)
  • description (String)
  • last_activity_time (DateTime)
  • name (String)
  • setup_complete (DateTime)
  • uid (ID)
  • updated_at (DateTime)
Relationships
  • labels (Label, ToMany)
  • active_prediction_model (PredictionModel ToOne)
  • benchmarks (Benchmark ToMany)
  • created_by (User ToOne)
  • datasets (Dataset ToMany)
  • labeling_frontend (LabelingFrontend ToOne)
  • labeling_frontend_options (LabelingFrontendOptions ToMany)
  • labeling_parameter_overrides (LabelingParameterOverride ToMany)
  • organization (Organization ToOne)
  • predictions (Prediction ToMany)
  • reviews (Review ToMany)
  • webhooks (Webhook ToMany)
Object Methods

create_label(self, **kwargs)

Creates a label on this Project.

  • Kwargs: Label attributes. At the minimum the label `DataRow`.

create_prediction(self, label, data_row, prediction_model)

Creates a Prediction within this Project.

create_prediction_model(self, name, version)

Creates a PredictionModel connected to this Project.

delete(self)

Deletes this DB object from the DB (server side). After a call to this you should not use this DB object anymore.

export_labels(self, timeout_seconds=60)

Calls the server-side Label exporting that generates a JSON payload, and returns the URL to that payload. Will only generate a new URL at a max frequency of 30 min.

  • Args:
    • timeout_seconds (float): Max waiting time, in seconds.
  • Returns: URL of the data file with this Project's labels. If the server didn't generate during the `timeout_seconds` period, None is returned.

extend_reservations(self, queue_type)

Extends all the current reservations for the current user on the given queue type.

  • Args:
    • queue_type (str): Either "LabelingQueue" or "ReviewQueue"
  • Returns: int, the number of reservations that were extended.

labeler_performance(self)

Returns the labeler performances for this Project.

labels(self, datasets, order_by)

Custom relationship expansion method to support limited filtering.

  • Args:
    • datasets (iterable of Datasets>Dataset>Datasets>Datasets>Dataset): Optional collection of Datasets whose Labels>Labels>Labels>Labels>Labels are sought. If not provided, all Labels in this Project are returned.
    • order_by (None or (Field, Field.Order)): Ordering clause.

review_metrics(self, net_score)

Returns this Project's review metrics.

  • Args:
    • net_score (None or Review.NetScore): Indicates desired metric.
  • Returns: int, aggregation count of reviews for given net_score.

set_labeling_parameter_overrides(self, data)

Adds labeling parameter overrides to this project. Example:

>>> project.set_labeling_parameter_overrides([
>>> (data_row_1, 2, 3), (data_row_2, 1, 4)])
  • Args:
    • data (iterable): An iterable of tuples. Each tuple must contain (DataRow, priority, numberOfLabels) for the new override.
  • Returns: bool, indicates if the operation was a success.

setup(self, labeling_frontend, labeling_frontend_options)

Finalizes the Project setup.

  • Args:
    • labeling_frontend (LabelingFrontend): Which UI to use to label the data.
    • labeling_frontend_options (dict or str): Labeling frontend options, a.k.a. project ontology. If given a `dict` it will be converted to `str` using `json.dumps`.

unset_labeling_parameter_overrides(self, data_rows)

Removes labeling parameter overrides to this project.

  • Args:
    • data_rows (iterable): An iterable of DataRows.
  • Returns: bool, indicates if the operation was a success.

update(self, **kwargs)

Updates this DB object with new values. Values should be passed as key-value arguments with field names as keys:

>>> db_object.update(name="New name", title="A title")
  • Kwargs: Key-value arguments defining which fields should be updated for which values. Keys must be field names in this DB object's type.
  • Raises:

upsert_review_queue(self, quota_factor)

Reinitiates the review queue for this project.

  • Args:
    • quota_factor (float): Which part (percentage) of the queue to reinitiate. Between 0 and 1.

Dataset

Class labelbox.schema.dataset.Dataset (Updateable, Deletable).

A dataset is a collection of DataRows>DataRows. For example, if you have a CSV with 100 rows, you will have 1 Dataset and 100 DataRows.

Fields
  • created_at (DateTime)
  • description (String)
  • name (String)
  • uid (ID)
  • updated_at (DateTime)
Relationships
Object Methods

create_data_row(self, **kwargs)

Creates a single DataRow belonging to this dataset.

>>> dataset.create_data_row(row_data="http://my_site.com/photos/img_01.jpg")
  • Kwargs: Key-value arguments containing new `DataRow` data. At a minimum `kwargs` must contain `row_data`. The value for `row_data` is a string. If it is a path to an existing local file then it is uploaded to Labelbox's server. Otherwise it is treated as an external URL.
  • Raises:

create_data_rows(self, items)

Creates multiple DataRow>DataRow>DataRow>DataRow objects based on the given `items`. Each element in `items` can be either a `str` or a `dict`. If it is a `str`, then it is interpreted as a local file path. The file is uploaded to Labelbox and a DataRow>DataRow>DataRow referencing it is created. If an item is a `dict`, then it should map `DataRow>DataRow` fields (or their names) to values. At the minimum an `item` passed as a `dict` must contain a `DataRow.row_data` key and value.

>>> dataset.create_data_rows([
>>> {DataRow.row_data:"http://my_site.com/photos/img_01.jpg"},
>>> "path/to/file2.jpg"
>>> ])
  • Args:
    • items (iterable of (dict or str)): See above for details.
  • Returns: Task>Task representing the data import on the server side. The Task can be used for inspecting task progress and waiting until it's done.
  • Raises:

data_row_for_external_id(self, external_id)

Convenience method for getting a single `DataRow` belonging to this `Dataset` that has the given `external_id`.

delete(self)

Deletes this DB object from the DB (server side). After a call to this you should not use this DB object anymore.

update(self, **kwargs)

Updates this DB object with new values. Values should be passed as key-value arguments with field names as keys:

>>> db_object.update(name="New name", title="A title")
  • Kwargs: Key-value arguments defining which fields should be updated for which values. Keys must be field names in this DB object's type.
  • Raises:

DataRow

Class labelbox.schema.data_row.DataRow (Updateable, BulkDeletable).

A DataRows>DataRow represents a single piece of data. For example, if you have a CSV with 100 rows, you will have 1 Dataset and 100 DataRows.

Fields
  • created_at (DateTime)
  • external_id (String)
  • row_data (String)
  • uid (ID)
  • updated_at (DateTime)
Relationships
Static Methods

bulk_delete(data_rows)

Deletes all the given DataRows.

Object Methods

create_metadata(self, meta_type, meta_value)

Creates an asset metadata for this DataRow.

  • Args:
    • meta_type (str): Asset metadata type, must be one of: VIDEO, IMAGE, TEXT.
    • meta_value (str): Asset metadata value.
  • Returns: AssetMetadata DB object.

delete(self)

Deletes this DB object from the DB (server side). After a call to this you should not use this DB object anymore.

update(self, **kwargs)

Updates this DB object with new values. Values should be passed as key-value arguments with field names as keys:

>>> db_object.update(name="New name", title="A title")
  • Kwargs: Key-value arguments defining which fields should be updated for which values. Keys must be field names in this DB object's type.
  • Raises:

Label

Class labelbox.schema.label.Label (Updateable, BulkDeletable).

Label represents an assessment on a DataRow. For example one label could contain 100 bounding boxes (annotations).

Fields
  • agreement (Float)
  • benchmark_agreement (Float)
  • is_benchmark_reference (Boolean)
  • label (String)
  • seconds_to_label (Float)
  • uid (ID)
Relationships
Static Methods

bulk_delete(labels)

Deletes all the given Labels.

Object Methods

create_benchmark(self)

Creates a Benchmark for this Label.

  • Returns: The newly created Benchmark.

create_review(self, **kwargs)

Creates a Review for this label.

  • Kwargs: Review>Review attributes. At a minimum a `Review.score` field value must be provided.

delete(self)

Deletes this DB object from the DB (server side). After a call to this you should not use this DB object anymore.

update(self, **kwargs)

Updates this DB object with new values. Values should be passed as key-value arguments with field names as keys:

>>> db_object.update(name="New name", title="A title")
  • Kwargs: Key-value arguments defining which fields should be updated for which values. Keys must be field names in this DB object's type.
  • Raises:

AssetMetadata

Class labelbox.schema.asset_metadata.AssetMetadata.

AssetMetadata is a datatype to provide extra context about an asset while labeling.

Constants
  • VIDEO (str)
  • IMAGE (str)
  • TEXT (str)
Fields
  • meta_type (String)
  • meta_value (String)
  • uid (ID)
Relationships

LabelingFrontend

Class labelbox.schema.labeling_frontend.LabelingFrontend.

Is a type representing an HTML / JavaScript UI that is used to generate labels. “Image Labeling” is the default Labeling Frontend that comes in every organization. You can create new labeling frontends for an organization.

Fields
  • description (String)
  • iframe_url_path (String)
  • name (String)
  • uid (ID)
Relationships

Task

Class labelbox.schema.task.Task.

Represents a server-side process that might take a longer time to process. Allows the Task state to be updated and checked on the client side.

Fields
  • completion_percentage (Float)
  • created_at (DateTime)
  • name (String)
  • status (String)
  • uid (ID)
  • updated_at (DateTime)
Relationships
Object Methods

refresh(self)

Refreshes Task data from the server.

wait_till_done(self, timeout_seconds=60)

Waits until the task is completed. Periodically queries the server to update the task attributes.

  • Args:
    • timeout_seconds (float): Maximum time this method can block, in seconds. Defaults to one minute.

Webhook

Class labelbox.schema.webhook.Webhook (Updateable).

Represents a server-side rule for sending notifications to a web-server whenever one of several predefined actions happens within a context of a Project or an Organization.

Constants
  • ACTIVE (str)
  • INACTIVE (str)
  • REVOKED (str)
  • LABEL_CREATED (str)
  • LABEL_UPDATED (str)
  • LABEL_DELETED (str)
Fields
  • created_at (DateTime)
  • status (String)
  • topics (String)
  • uid (ID)
  • updated_at (DateTime)
  • url (String)
Relationships
Static Methods

create(client, topics, url, secret, project)

Creates a Webhook.

  • Args:
    • client (Client): The Labelbox client used to connect to the server.
    • topics (list of str): A list of topics this Webhook should get notifications for.
    • url (str): The URL to which notifications should be sent by the Labelbox server.
    • secret (str): A secret key used for signing notifications.
    • project (Project or None): The project for which notifications should be sent. If None notifications are sent for all events in your organization.
  • Returns: A newly created Webhook.
Object Methods

update(self, topics, url, status)

Updates this Webhook.

  • Args:
    • topics (list of str): The new topics value, optional.
    • url (str): The new URL value, optional.
    • status (str): The new status value, optional.

User

Class labelbox.schema.user.User.

A User is a registered Labelbox user (for example you) associated with data they create or import and an Organization they belong to.

Fields
  • created_at (DateTime)
  • email (String)
  • intercom_hash (String)
  • is_external_user (Boolean)
  • is_viewer (Boolean)
  • nickname (String)
  • name (String)
  • picture (String)
  • uid (ID)
  • updated_at (DateTime)
Relationships

Organization

Class labelbox.schema.organization.Organization.

An Organization>Organization>Organization>Organization is a group of User>Users>Users>Users associated with data created by User>Users>Users within that Organization>Organization>Organization. Typically all User>Users within an Organization>Organization have access to data created by any User in the same Organization.

Fields
  • created_at (DateTime)
  • name (String)
  • uid (ID)
  • updated_at (DateTime)
Relationships

Review

Class labelbox.schema.review.Review (Updateable, Deletable).

Reviewing labeled data is a collaborative quality assurance technique. A Review object indicates the quality of the assigned Label. The aggregated review numbers can be obtained on a Project object.

Constants
  • Enumeration NetScore
    • Negative
    • Zero
    • Positive
Fields
  • created_at (DateTime)
  • score (Float)
  • uid (ID)
  • updated_at (DateTime)
Relationships
Object Methods

delete(self)

Deletes this DB object from the DB (server side). After a call to this you should not use this DB object anymore.

update(self, **kwargs)

Updates this DB object with new values. Values should be passed as key-value arguments with field names as keys:

>>> db_object.update(name="New name", title="A title")
  • Kwargs: Key-value arguments defining which fields should be updated for which values. Keys must be field names in this DB object's type.
  • Raises:

Prediction

Class labelbox.schema.prediction.Prediction.

A prediction created by a PredictionModel.

Fields
  • agreement (Float)
  • created_at (DateTime)
  • label (String)
  • uid (ID)
  • updated_at (DateTime)
Relationships

PredictionModel

Class labelbox.schema.prediction.PredictionModel.

A prediction model represents a specific version of a model.

Fields
  • created_at (DateTime)
  • name (String)
  • slug (String)
  • uid (ID)
  • updated_at (DateTime)
  • version (Int)
Relationships

LabelerPerformance

Class labelbox.schema.project.LabelerPerformance.

Named tuple containing info about a labeler's performance.

Error Classes

LabelboxError

Class labelbox.exceptions.LabelboxError.

Base class for exceptions.

AuthenticationError

Class labelbox.exceptions.AuthenticationError.

Raised when an API key fails authentication.

AuthorizationError

Class labelbox.exceptions.AuthorizationError.

Raised when a user is unauthorized to perform the given request.

ResourceNotFoundError

Class labelbox.exceptions.ResourceNotFoundError.

Exception raised when a given resource is not found.

ValidationFailedError

Class labelbox.exceptions.ValidationFailedError.

Exception raised for when a GraphQL query fails validation (query cost, etc.) E.g. a query that is too expensive, or depth is too deep.

InvalidQueryError

Class labelbox.exceptions.InvalidQueryError.

Indicates a malconstructed or unsupported query (either by GraphQL in general or by Labelbox specifically). This can be the result of either client or server side query validation.

NetworkError

Class labelbox.exceptions.NetworkError.

Raised when an HTTPError occurs.

TimeoutError

Class labelbox.exceptions.TimeoutError.

Raised when a request times-out.

InvalidAttributeError

Class labelbox.exceptions.InvalidAttributeError.

Raised when a field (name or Field instance) is not valid or found for a specific DB object type.

ApiLimitError

Class labelbox.exceptions.ApiLimitError.

Raised when the user performs too many requests in a short period of time.


Was this page helpful?