API reference

Updated 2 weeks ago by Florijan Stamenkovic

General Classes
Data Classes
Error Classes

General classes

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')

Create and initialize 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.

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

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

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)
  • 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)
  • 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`.

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.

  • 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)

Extend 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 Dataset): Optional collection of Datasets whose 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 indicating if the operation was a success.

setup(self, labeling_frontend, labeling_frontend_options)

Finalizes the Project setup.

  • Args:
    • labeling_frontend (LabelingFrontend): The labeling frontend to use.
    • 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 indicating 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)

Reinitiate the review queue for this project.

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

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

A dataset is a collection of 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.

  • Kwargs: Key-value arguments containing new `DataRow` data. At a minimum they must contain `row_data`. The value for `row_data` is a string. If it's a path to an existing local file then it's uploaded to Labelbox's server. Otherwise it's treated as an external URL.
  • Raises:

create_data_rows(self, items)

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

  • Args:
    • items (iterable of (dict or str)): See above for details.
  • Returns: 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:
    • InvalidQueryError: if the `items` parameter does not conform to the specification above.
    • MalformedRequestError: if the server did not accept the DataRow creation request.
    • ResourceNotFoundError: if unable to retrieve the Task based on the task_id of the import process. This could imply that the import failed.
    • InvalidAttributeError: if there are fields in `items` not valid for a DataRow.

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:

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

A 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:

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 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:

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

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

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.

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.

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

Class labelbox.schema.organization.Organization

An Organization is a group of Users associated with data created by Users within that Organization. Typically all Users within an 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

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:

Class labelbox.schema.project.LabelerPerformance

Named tuple containing info about a labeler's performance.

Error Classes

Class labelbox.exceptions.LabelboxError

Base class for exceptions.

Class labelbox.exceptions.AuthenticationError

Raised when an API key fails authentication.

Class labelbox.exceptions.AuthorizationError

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

Class labelbox.exceptions.ResourceNotFoundError

Exception raised when a given resource is not found.

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.

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.

Class labelbox.exceptions.NetworkError

Raised when an HTTPError occurs.

Class labelbox.exceptions.TimeoutError

Raised when a request times-out.

Class labelbox.exceptions.InvalidAttributeError

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

Class labelbox.exceptions.ApiLimitError

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


How did we do?