Labelbox GraphQL API

What is GraphQL?

GraphQL is an API query language and a server-side runtime for executing queries. Everything in GraphQL revolves around a schema, which represents all the data in your system and the type of data it is.

Why does Labelbox use GraphQL?

We chose to use GraphQL to structure our API because it provides more flexibility than REST. Here are some advantages GraphQL offers:

Strongly-typed schema

Both the request query and the response are strongly typed. You will know your query is valid because the schema will not allow improperly written schemas.

Hierarchical structure

Each GraphQL query and response takes the shape of a hierarchical set of fields. This makes the queries easy to create and the responses intuitive to read.

Flexibility

With GraphQL you can get all the data you need in one single request allowing for quicker, more precise data retrieval.

Specificity

Unlike in a REST API, a GraphQL response will include only the data you specify in your query.

Strong tooling

Tools like our API explorer allow you to explore the API schema and run queries in your browser.

Root operation types

Our GraphQL API makes use of two operation types, Query and Mutation. These are special because they provide the entry point for every GraphQL query. We encourage you to experiment with these operation types in our API explorer.

Fields, arguments & object types

Fields, arguments, and object types are used to construct the schema. The Query fields perform read-only operations and the Mutation fields perform writes.

The createLabel example below is a Mutation field.

5f1a042cf3dbd.png

Fields allow you to perform specialized operations within the Query and Mutation root operation types. The createLabel field in the example above requires an argument and targets the Label object type.

Arguments are defined by name and type and serve a variety of purposes. Each field can have zero or more arguments. In the example above, the data: LabelCreateInput argument is required as specified by the (!) symbol.

Object types are the entities in the database that receive the action performed by the field. For the createLabel field, the Label object type is required as specified by the (!) symbol.

Using the API explorer

In the API explorer, run the following query:

This query retrieves your own user information. In GraphQL terminology, user is our root object from which we select all of its fields we want to retrieve (id, email, role) and a sub-object: organization. Hovering over the syntax will give more information about each object/field.

The Documentation Explorer to the upper right provides more Schema details; try searching "User" to explore other fields you can select.

5f1a042e74334.png
query GetUserInfo { 
    user { 
        id
        email
        role
        organization { 
            id
            name
        } 
        projects { 
            id
            name
        }
    }
}

Creating parameterized queries

We can use some of the data we just retrieved to construct a more involved query. Copy and paste the project ID into the Query Variables section in the bottom left pane, like so:

{ "project_id" : "<PROJECT ID HERE>" }

In the main text window, run the following:

This time, we've created a function for our query by naming it ByProjects and assigning it a parameter, $project_id of type ID. In the bottom pane, we've tossed our function an argument for project ID. The resulting data is the member info for only the project we specified.

query ByProjects ($project_id: ID!) { 
    projects (where: {id_contains: $project_id}) { 
        members { 
            user { 
                email
                id
                role
            }
        }
    }
}

Getting started

Root endpoint

https://api.labelbox.com/graphql

Create API key

  1. Click “Account” from the upper-right dropdown menu.

  2. From the API tab, click “Create API Key”.

  3. Copy the API key to your clipboard by clicking the blue icon. The API key will be hidden once you leave this page so make sure to save your API Key somewhere else.

Authentication

Authentication tokens (API Keys) are accepted by our GraphQL API in one of two ways.

  • Provide as an authorization header [RECOMMENDED]:

  • Provide as a query parameter. We do not recommend sending API keys as a query parameter for GraphQL queries.

# Pass API key as a header to make a graphql query
curl 'https://api.labelbox.com/graphql' \
   -H 'Authorization: Bearer <API_KEY_HERE>' \
   -H 'content-type: application/json' \
   -d '{"query":"[QUERY HERE]"}'

# Pass API key as a header to request a mask for an annotated object
curl 'https://api.labelbox.com/masks/feature/:id' \
   -H 'Authorization: Bearer <API_KEY_HERE>'   
# Passing API key as a query parameter to request a mask for an annotated object
curl 'https://api.labelbox.com/masks/feature/:id?token=<API_KEY_HERE>'

Annotation counts

Annotation count is the sum of the billable annotations created by the team members in your organization.

Get annotation count

To get the billable annotation count for your organization, use the annotationCounts query and specify a date range. If startDate and endDate are both absent, the API returns all available data.

This sample query will get the annotation counts for a single date, 02/08/2021.

Field

Type

Description

startDate

Date

UTC date in YYYY-MM-DD format. The startDate you specify is included in the date range.

endDate

Date

UTC date in YYYY-MM-DD format. The endDate you specify is excluded from the date range.

orderBy

Enum

Values are: CREATION_DATE_ASC and CREATION_DATE_DESC. Note: orderBy is optional. If unspecified, results will return in ASC order (ie. default value is CREATION_DATE_ASC)

The annotationCounts query returns a list of AnnotationCount objects with the following properties.

Field

Type

Description

image

Int

Cumulative counts of image annotations for the specified date.

video

Int

Cumulative counts of video annotations for the specified date.

text

Int

Cumulative counts of text annotations for the specified date.

creationDate

Date

If annotation counts are not available for a given date, that date's AnnotationCount object will be absent from the response.

updateTime

DateTime

When creationDate's data was last updated.

query GetAnnotationCount {
    annotationCounts (where: {startDate: "2021-02-08", endDate: "2021-02-09"}, orderBy: CREATION_DATE_ASC){
        image
        video
        text
        creationDate
        updateTime
    }
}

Attachments

Attachments are media you can attach to a Data Row to provide labelers with contextual information about the asset to be labeled.

Note

In an effort to make the Labelbox terminology more accurate, we have renamed asset metadata to attachments in this context. Please use the updated queries and mutations below going forward.

Add attachments

To add attachments to a Data Row, use the createAssetAttachment mutation (previously createAssetMetadata). To attach more than one image, video, or text string, you will need to run the createAssetAttachment mutation multiple times which will append the attachment to the existing attachments on that Data Row.

Field

Type

Description

data.dataRowId

ID

ID of the Data Row to add the attachments to

data.value

String

Accepts an https URL to an external file OR a string of text

data.type

AttachmentType

Values are:

IMAGE, VIDEO, TEXT, IMAGE_OVERLAY

mutation AddAttachment {
    createAssetAttachment (
        data:{
            dataRowId:"<DATAROW_ID>",
            value:"https://firebasestorage.googleapis.com/v0/b/labelbox-193903.appspot.com/o/cjhk4p9dyf5va0702liitudpz%2Fd3ffab29-d6be-4d69-b006-89a828679d29%2Fleft_small-pen-test-site_1_1537524039648.jpg?alt=media&token=66e84e55-97e8-46a6-9ab8-685f1e950581",
            type: IMAGE
        }
    ) {
        id
    }
}

Get attachments

Use this query to get the list of attachments (previously called asset metadata).

Field

Type

Description

attachments.id

ID

ID of the Attachment on the Data Row.

attachments.type

AttachmentType

Attachment type. Should be IMAGE, VIDEO, TEXT, or IMAGE_OVERLAY.

attachments.value

String

An https URL to an external file or a string of text.

query GetAttachmentByDataRowId {
    dataRow (where: {id: "<DATAROW_ID>"}) {
        attachments {
            id
            type
            value
        }
    }
}
# metadata in this context will soon be deprecated
query GetAttachmentByDataRowId {
    dataRow (where: {id: "<DATAROW_ID>"}) {
        metadata {
            id
            metaValue
            metaType
        }
    }
}

Edit attachments

First, use this query to get the ID for the attachments (previously referred to as metadata).

Then, use updateAssetAttachment (previously updateAssetMetadata) to update an attachment on a Data Row.

Field

Type

Description

data.value

String

Accepts an https URL to an external file OR a string of text

data.type

AttachmentType

Values are:

IMAGE, VIDEO, TEXT, IMAGE_OVERLAY

query GetAttachmentId {
    dataRow (where: {id: "<DATAROW_ID>"}) {
        id
        attachments {
            id
        }
    }
}
mutation UpdateAttachment {
    updateAssetAttachment (
        where: {
            id:"<ATTACHMENT_ID>"
        },
        data:{
            value:"https://storage.googleapis.com/labelbox-sample-datasets/nlp/lorem-ipsum.txt",
            type: TEXT
        }
    ){
        id
    }
}

Remove attachments

Then, use the deleteAssetAttachment (previously deleteAssetMetadata) mutation to remove the attachments.

mutation RemoveAssetAttachment {
  deleteAssetAttachment (
    where: {
      id:"<ATTACHMENT_ID>"
    }
  ){
    id
    type
  }
}

Bulk import requests

bulkImportRequest represents the bulk import job for a set of predictions.

For an overview of this workflow, see our docs on Model-assisted labeling.

Create a bulk import request

After you create your import file (see our Data model reference for annotation import formats), create a public URL for your file. Then, use the createBulkImportRequest mutation to create an import job.

Field

Type

Description

projectId

ID

Project to import the annotations

name

String

Name of the import job

fileUrl

String

Valid URL to an NDJSON file containing the annotations

Caution

Wait until the import job is complete before opening the Editor to make sure all annotations are imported properly.

mutation CreateBulkImportRequest {
    createBulkImportRequest (data: {
        projectId: "<PROJECT_ID>",
        name: "import_job_1",
        fileUrl: "https://foobar.com/test2file"
    }) {
    id
  }
}

Check import request status

Use the bulkImportRequest query to check the status of the import job.

This query returns the following fields.

Field

Type

Definition

state

BulkImportRequestState

Refers to the whole import job and the values are: RUNNING, FAILED, FINISHED.

statusFileUrl

String

Points to an NDJSON that expires after 24 hours and contains a SUCCESS or FAILED status per annotation when state is FINISHED. When state is FAILEDstatusFileUrl will be null.

errorFileUrl

String

Points to an NDJSON that contains error messages for each annotation that did not import successfully when state is FINISHED.When state is FAILED, this NDJSON contains the error message.

query CheckImportRequestStatus {
    bulkImportRequest (where: {
        projectId: "<PROJECT_ID>",
        name: "import_job_1"
    }) {
        state
        statusFileUrl
        errorFileUrl
    }
}

List all import requests

Use this bulkImportRequests query to return a list of each import request that is accessible to you (Note: bulkImportRequests is plural). Use the following arguments to filter your query.

Argument

Type

Description

skip

Int

Indicates the number of items to skip over.

first

PageSize

Indicates the max number of items to return.

query ListAllImportRequests {
    bulkImportRequests (
        where: { projectId: "<PROJECT_ID>" } 
        skip: 0 
        first: 100
    ) {
        id
        name
    }
}

Delete imported annotations

Use this mutation to delete all imported annotations associated with a bulkImportRequest (note: this mutation does not delete the import request itself).

Labelbox handles each deleteBulkImportRequest atomically, meaning either all or none of the annotations will be deleted depending on whether or not the deletion is successful.

If you open the asset with the imported annotations in the Editor before using the deleteBulkImportRequest mutation, you may need to refresh the screen to see the annotations removed from the labeling interface.

mutation DeleteBulkImportRequest {
    deleteBulkImportRequest (where: {id: "<IMPORT_REQUEST_ID>"}) {
        id
        name
    }
}

Data Rows

A Data Row is the internal Labelbox representation of an asset.

Bulk import data rows

Before you import, make sure your JSON file is formatted properly (see our Data model reference for data import formats). Then, use the appendRowsToDataset mutation to create data rows from the JSON file.

Field

Type

Definition

datasetId

ID

Dataset ID

jsonFileUrl

String

Public https URL to the JSON file containing the data to be labeled

mutation AppendRowsToDataset { 
    appendRowsToDataset ( 
        data: { 
            datasetId:"<DATASET_ID>", 
            jsonFileUrl:"<PUBLIC_URL_TO_JSON_FILE>" 
        } 
    ){ 
        accepted 
    }
}

Individual import

Use the createDataRow mutation to import data by URL and attach it to an existing project.

Field

Type

Definition

externalId

String

User generated filename

rowData

String

An https URL to the asset to be labeled

dataset.connect.id

ID

Dataset to connect the data row to

mutation CreateDataRow { 
    createDataRow ( 
        data: { 
            externalId: "<EXTERNAL_ID>", 
            rowData: "<ASSET_URL>", 
            dataset: { 
                connect: { 
                    id: "<DATASET_ID>" 
                } 
            },
        } 
    ){ 
        id 
    }
}

Get all data rows in a dataset

Use the datasets query to return all Data Rows from a Dataset. For a complete list of fields for data rows, see the Docs tab in the API explorer.

query GetDataRows {
    datasets (where: {id: "<DATASET_ID>"}) { 
        name 
        id 
        dataRows { 
            id 
            externalId 
        } 
    }
}

Get all data rows in a project

Specify the number of data rows to retrieve within the project query. For a complete list of arguments for dataRows see the Docs tab in the API explorer.

query GetDataRowsByProject { 
    project (where: {id: "<PROJECT_ID>"}) { 
        datasets { 
            dataRows (first: 100) { 
                id 
                rowData 
                externalId 
            }     
        } 
    }
}

Update data rows

Use the updateDataRow mutation to update data row fields.

Field

Type

Definition

externalId

String

User-generated file name

rowData

String

https URL to the asset to be labeled

mutation UpdateDataRow { 
    updateDataRow ( 
        where: {id: "<DATAROW_ID>"} 
        data: {
            externalId: "<NEW_FILENAME>",
            rowData: "<NEW_ASSET_URL>"
        } 
    ){ 
    id
}

Delete data rows

The deleteDataRows mutation can take a list of up to 10,000 dataRowIds.

Caution

Cascading delete - if you delete a data row it will also delete the attached labels. Once deleted, there is no API method to undelete a data row.

mutation DeleteDataRows { 
    deleteDataRows (where:{ 
        dataRowIds:["<DATA_ROW_ID>"] 
    }){ 
        id 
        deleted 
    }
}

Datasets

A Dataset is a collection of Data Rows and can span multiple Projects. For a complete list of fields for Dataset, visit the Docs tab in the API explorer.

Create a dataset

Use the createDataset mutation to create a dataset and connect it to a project.

Field

Type

Description

name

String

Dataset name

projects.connect.id

ID

ID of the project to connect the dataset to

mutation CreateDataset { 
    createDataset ( 
        data: { 
            name: "<DATASET_NAME>", 
            projects: {
                connect: {
                    id: "<PROJECT_ID>"
                }
            } 
        } 
    ) { 
        id 
    }
}

Attach a dataset

Use the updateProject mutation to connect an existing dataset to a project.

Field

Type

Description

datasets.connect.id

ID

ID of the dataset to connect to the project

mutation AttachDataset { 
    updateProject ( 
        where: { 
            id:"<PROJECT_ID>" 
        }, 
        data:{ 
            datasets: { 
                connect: { 
                    id: "<DATASET_ID>" 
                } 
            } 
        } 
    ){ 
        id 
    } 
}

Get a dataset

Use the dataset query to get a dataset by id. For a complete list of Dataset fields, see the Docs tab in the API explorer.

query GetDataset { 
    dataset (where: {id: "<DATASET_ID>"}) { 
        name 
        description 
        projects { 
            id
        } 
        createdAt 
        createdBy { 
            id 
        } 
        rowCount 
    }
}

Update a dataset

Use the updateDataset mutation to update dataset fields.

Field

Type

Description

name

string

Dataset name

description

string

Dataset description

mutation UpdateDataset { 
    updateDataset ( 
        where: { 
            id: "<DATASET_ID>"
        }, 
        data: { 
            name: "<NEW_NAME>", 
            description: "<NEW_DESCRIPTION>" 
        } 
    ) { 
        id 
    }
}

Delete a dataset

Use the updateDataset mutation to delete a dataset.

Field

Type

Description

deleted

boolean

To delete a dataset, set to true.

mutation UpdateDataset { 
    updateDataset ( 
        where: { 
            id: "<DATASET_ID>" 
        }, 
        data: { 
            deleted: true 
        } 
    ) { 
        id 
    }
}

Integrations

Use these GraphQL operations to configure IAM Delegated Access programmatically. To learn more, see our Delegated Access docs.

To view a sample script for setting this up, see our IAM Delegated Access colab notebook.

Integration setup

Follow these steps to set up IAM Delegated Access via the GraphQL API.

  1. Use the createAwsIamIntegration mutation to create a new AWS IAM integration. See a sample mutation here. The id value returned is the Labelbox External ID. The Labelbox AWS account ID is 340636424752.

  2. Follow steps 3-4 in the Configure integration in AWS docs to set up the role and permission policy for Labelbox in your AWS account.

  3. In your AWS account, go to Services > IAM > Roles, click on your newly created role, and copy the Role ARN (e.g.,

    arn:aws:iam::123456789:role/MyRole).

  4. Use the updateAwsIamIntegration mutation to update your Labelbox IAM integration with the Role ARN. See a sample mutation here.

  5. Validate your integration with the validateIamIntegration mutation. See a sample mutation here.

  6. Create an empty dataset in Labelbox. See a sample createDataset mutation here.

  7. Use the setSignerForDataset mutation to attach the IAM integration to your dataset. See a sample mutation here.

  8. Set up CORS headers for your S3 bucket.

  9. Create your JSON file containing your URLs and add your data to your dataset. The validateDataset mutation in the next step will only provide useful feedback if the dataset contains at least one data row.

  10. Use the validateDataset mutation to make sure the IAM integration is working properly for your dataset. This returns a payload with the status of the various checks that you can use for troubleshooting. See a sample mutation here.

Your dataset should now be set up with IAM Delegated Access. Labelbox will use the AWS role you created to generate temporary signed URLs every time it accesses data in your S3 bucket.

Get integration ID

Use this query to get a list of all IAM integrations.

query GetIntegrations {
  iamIntegrations {
    id
    name
  }
}

Create integration

Use the createAwsIamIntegration mutation to create a Delegated Access integration between your S3 bucket and Labelbox.

Specifying the roleArn when you are creating the integration is optional.

The id returned from this createAwsIntegration mutation is the Labelbox External ID. The Labelbox AWS account ID is 340636424752.

Field

Type

Description

name

String

The name of the new IAM integration.

roleArn

String

The ARN (Amazon Resource Name) for the role created for Labelbox in your AWS account. If you do not have a role yet, you can leave out roleArn.

mutation CreateIntegration {
    createAwsIamIntegration (data: { 
      name: "AWS IAM Integration" 
      roleArn: "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>"
    }) {
	id
    }
}

Validate integration

Use the validateIamIntegration mutation to ensure that the integration you set up via IAM was configured properly.

Field

Type

Description

valid

Boolean

Indicates whether the IAM integration is valid.

name

IamIntegrationValidationCheckName

Values are AWSAssumeRole and AWSExternalID. See Troubleshooting for more information.

success

Boolean

Indicates whether the check was successful.

mutation CheckIntegration {
  validateIamIntegration (where: {id: "<INTEGRATION_ID>"}) {
    valid
    checks { 
      name
      success
    }
  }
}

Update integration

Use the updateAwsIamIntegration mutation to update the role ARN associated with the integration. Use the where argument to specify which integration you want to update and the data argument to specify what you want to update (i.e., roleArn or name).

Field

Type

Description

name

String

Name of the IAM integration you want to update.

roleArn

String

ARN of the IAM integration you want to update.

id

ID

ID for the integration you created via the createAwsIamIntegration mutation.

mutation UpdateIntegration {
    updateAwsIamIntegration (
        data: { 
            roleArn: "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"
            name: "<NEW_INTEGRATION_NAME>"
        },
	where: { 
            id: "<INTEGRATION_ID>" 
        }) {
            id
        }
}

Attach integration to dataset

Use the setSignerForDataset mutation to attach an IAM integration to your dataset. Use the where argument to specify the dataset and the data argument to specify what to change.

Field

Type

Description

signerId

ID

The ID of an IAM integration to use as a signer for the dataset.

id

ID

Dataset ID.

mutation SetSignerForDataset {
    setSignerForDataset (
	data: { signerId: "<INTEGRATION_ID>" },
	where: { id: "<DATASET_ID>" }) {
	    id
	    signer {
		id
	}
    }
}

Validate dataset

When you create your dataset via the GraphQL API, you'll need to run a dataset validation yourself. Use the validateDataset mutation to do this.

This returns a payload with the status of the various checks that you can use for troubleshooting.

Field

Type

Description

valid

Boolean

Indicates whether the dataset was connected to the IAM integration successfully.

name

DatasetValidationCheckName

Values are CORSPreflight and FetchAsset. For more information, see the Troubleshooting section.

success

Boolean

Indicates whether the dataset validation check was successful.

mutation ValidateDataset {
  validateDataset (where: {id: "<DATASET_ID>"}){
    valid
    checks {
      name
      success
    }
  }
}

Labeling parameters

In order to customize your Label queue, you need to specify the labeling parameters. For an overview of queue prioritization, see our docs on the Queue system.

Set parameter overrides

Use setLabelingParameterOverrides to set all parameter overrides in one mutation. Then, you need to rebuild the queue. For more information on how to do this programmatically, contact our support team.

Field

Type

Description

dataRow.id

WhereUniqueIdInput

ID of the data row you wish to set priority for. Max number of data rows you can include is 1000. Note: externalId not supported.

priority

Int

Place in the label queue

numLabels

Int

Number of times the asset should be labeled. This number should not exceed the number of labelers in the project.

Returns:

Field

Type

Description

success

Boolean

Returns false and gives you an error if the request was not properly received and processed. Will still return true if you submit one or more data rows that do not exist.

mutation SetLabelingParameterOverrides {
    project (where: { id: "<PROJECT_ID>" }) {
        setLabelingParameterOverrides (data:[
            { 
                dataRow: { id: "<DATA_ROW_ID>" }, 
                priority: 1, 
                numLabels: 2 
            },
            { 
                dataRow: { id: "<DATA_ROW_ID>" }, 
                priority: 2, 
                numLabels: 3 
            }
        ]) {
            success
        }
    }
}

Fetch parameter overrides

Use the project query to fetch any existing labeling parameter overrides.

query PullLabelingParameters {
    project (where: {id:"<PROJECT_ID>"}) {
        labelingParameterOverrides {
            id
            priority
        }
    }
}

Unset parameter overrides

Use the unsetLabelingParameterOverrides mutation to unset the prioritization for a set of Data Rows. Using this mutation will automatically result in the rebuild of the Label queue.

Field

Type

Description

dataRowId

ID

Data rows to remove parameter overrides from. The max number of data rows you may include in this mutation is 1000.

mutation UnsetLabelingParameterOverrides {
    project (where: { id: "<PROJECT_ID>" }) {
        unsetLabelingParameterOverrides (data:[
            { 
                dataRowId: "<DATA_ROW_ID>" 
            },
            { 
                dataRowId: "<DATA_ROW_ID>" 
            }
        ]) {
            success
        }
    }
}

Unset all parameter overrides

Use the unsetAllLabelingParameterOverrides to unset the labeling parameter overrides for all data rows in a project.

mutation UnsetAllParameterOverrides {
    project (where: {id: "<PROJECT_ID>"}) {
        unsetAllLabelingParameterOverrides {
            success
            deletedCount
        }
    }
}

Labels

A Label is a collection of annotations on a single asset and represents an assessment on a Data Row. For a complete list of Label fields, see the Docs tab in the API explorer.

Get JSON label by ID

To get the stringified JSON value for a label, use the label query.

query GetLabelById { 
    label(where: {id: "<LABEL_ID>"}) { 
        label 
    }
}

Get JSON label by project

Use the projects query to get a JSON label by project ID.

Argument

Type

Description

first

PageSize

Number of elements in the paginated result

skip

Int

Number of labeled assets from the project to skip

query GetLabelsFromProject {
    projects (where: {id: "<PROJECT_ID>"}) { 
        id 
        name 
        labels (first: 10) { 
            id 
            createdBy { 
                email 
            } 
            label 
        } 
    }
}

Individual export

Use the project query to export individual labels or a subset of labels.

Argument

Type

Description

first

PageSize

Number of elements in the paginated result

skip

Int

Number of labeled assets from the project to skip

query ApiGetPageOfLabels { 
    project (where:{id: "<PROJECT_ID>"}) { 
        labels (first: 5) { 
            id 
            label 
            createdBy { 
                id 
                email
            } 
            type { 
                id 
                name
            } 
            secondsToLabel 
            agreement 
            dataRow { 
                id 
                rowData 
            } 
        } 
    }
}

Bulk export

Use the exportLabels mutation to bulk export labels from your project.

Running this mutation should return:

Field

Type

Description

downloadUrl

String

URL to the JSON file containing the labels for the project. This mutation will generate a new downloadUrl no more than once every 30 min. If you call exportLabels twice within 30 min, the second call will return the same downloadUrl and createdAt timestamp.

createdat

String

Timestamp indicating when the export was generated

shouldPoll

Boolean

If true, indicates the export is in the process of being generated and your script should make the same request on an interval until completion.

mutation BulkExportLabels { 
    exportLabels (data: { 
        projectId: "<PROJECT_ID>" 
    }) { 
        downloadUrl 
        createdAt 
        shouldPoll 
    }
}

Delete labels

Use the deleteLabels mutation to remove all annotations from an asset. When you delete a label, the asset is automatically re-enqueued, meaning it is re-entered into the labeling queue.

mutation DeleteLabels { 
    deleteLabels ( 
        labelIds:["<LABEL_ID>"] 
    ){ 
        id 
        deleted 
    }
}

Keep deleted labels as templates

Use the bulkDeleteLabels mutation to keep deleted labels as templates.

Caution

When you delete a label but keep it as a template, the labeling time and any other metrics are not preserved, only the label itself.

Field

Type

Definition

makeTemplates

Boolean

Must be set to true to create templates from deleted labels

mutation BulkDeleteLabels (
    $projectId: ID!,
    $makeTemplates: Boolean = true,
    $labelsWhere: WhereBulkLabelDelete,
    $first: PageSize,
    $skip: Int ) {
    project (where: {id: $projectId}) {
        bulkDeleteLabels (
            where: $labelsWhere,
            makeTemplates: $makeTemplates,
            waitForQueue: true,
            first: $first,
            skip: $skip
        ) {
            count
        }
    }
}

Media attributes

Media attributes include any metadata about the Data Row (e.g., width, height, MIME type, etc).

Get data row media attributes

Use the dataRow query to get all available media attributes for a Data Row.

Field

Description

dataRow.id

Data Row of the asset (media) to query.

mediaAttributes

This will return the available attributes for the specified Data Row.

Response:

Note

Not all fields are guaranteed to be present and payload may differ based on asset type.

Field

Asset type

Type

Description

mimeType

Video, Image, Text, Tiled imagery

String

Media type. Will be one of the following:

  • video/mp4

  • image/jpeg

  • text/plain

  • application/x-tms-geo (tiled imagery: EPSG3857)

  • application/x-tms-simple (tiled imagery: Simple)

  • application/json (other)

width

Video, Image

Int

Image or frame width in pixels.

height

Video, Image

Int

Image or frame height in pixels.

codec

Video

String

Indicates the video compression standard.

duration

Video

Int

Duration of the video in seconds.

frameRate

Video

Int

Frame rate per second

frameCount

Video

Int

Number of frames in the video.

query GetDataRowMediaAttributes {
  dataRow (where: {id: "<DATAROW_ID>"}) {
    mediaAttributes
  }
}
// Sample response: video
{
  "data": {
    "dataRow": {
      "mediaAttributes": {
        "codec": "avc1",
        "width": 1920,
        "height": 1080,
        "duration": 10,
        "mimeType": "video/mp4",
        "frameRate": 10,
        "frameCount": 100
      }
   }
}
// Sample response: image
{
  "data": {
    "dataRow": {
      "mediaAttributes": {
        "width": 3872,
        "height": 2592,
        "mimeType": "image/jpeg"
      }
   }
}
// Sample response: text
{
  "data": {
    "dataRow": {
      "mediaAttributes": {
        "mimeType": "text/plain"
      }
   }
}
// Sample response: tiled imagery
{
  "data": {
    "dataRow": {
      "mediaAttributes": {
        "mimeType": "application/x-tms-geo"
      }
   }
}

Members

A member is an individual user in your organization. Members have permissions that can be configured at the organization-level or the project-level. Use the roles query to get the id for each role.

Add members at project-level

Use the addUserToProject mutation to add a member to a project and select their role.

Field

Type

Description

email

String

User email

projectId

String

ID of the project to add the member to

roleId

String

Admin: cjlvi91a41aab0714677xp87h

Team manager: cjlvi919q1aa80714b7z3xuku

Project-based: cjmb6xy80f5vz0780u3mw2rj4

Reviewer: cjlvi919b1aa50714k75euii5

Labeler: cjlvi914y1aa20714372uvzjv

mutation AddUserToProject { 
    addUserToProject ( 
        data: { 
            email: "<USER_EMAIL>", 
            projectId: "<PROJECT_ID>", 
            roleId: "<ROLE-ID>" 
        } 
    ) { 
        user { email } 
        project { name } 
        role { name } 
    }
}

Add members to an organization

Use the addMembersToOrganization mutation to add members and set their role at the organization-level.

Field

Type

Description

emails

String

Team member email

orgRoleId

ID

Organization role

projectRoles

ID

Leave empty

This sample mutation adds two new members as Admin at the Organization level.

mutation MakeNewUserAdmin { 
    addMembersToOrganization( 
        data: { 
            emails:["sample1@email.com", "sample2@email.com"], 
            orgRoleId: "cjlvi91a41aab0714677xp87h",
            projectRoles: []
        } 
    ) {
      newUserId
      existingUserEmail
      existingUserInviteSent
    }
}

Get available roles

Use the roles query to get the IDs for all of the member roles. Use the first argument to specify how many objects to return and the skip argument to specify how many objects to skip.

Field

Type

Definition

name

String

Role name

id

ID

Role ID

permissions

PermissionFlag

All available permissions for that role

query GetAvailableRoles { 
    roles (
        first: 10
        skip: 1
    ){ 
        name 
        id
    	permissions
    }
}

List member projects

Use the users query to get a list of all the projects a member is associated with.

query GetUserProjects { 
    users ( where: {email:"<USER-EMAIL>"}) {
        id 
        projects { 
            name 
            id 
        } 
    }
}

Remove members

Use this setProjectMembership mutation to remove project-based members.

Field

Type

Description

userId

ID

Member ID

roleId

ID

Set cjmb6xy80f5vz0780u3mw2rj4 as the roleId to set role to None.

projectId

ID

Project ID

mutation RemoveMemberFromProject {
    setProjectMembership (data: {
        userId:"<USER_ID>"
     	roleId: "cjmb6xy80f5vz0780u3mw2rj4"
     	projectId:"<PROJECT_ID>"
    }) {
        id  
    }
}

Ontologies

An Ontology contains all of the classes used for labeling assets in a Project.

For a complete list of fields for Ontology, see the Docs tab in the API explorer.

Get an ontology

Use the project query to get an existing ontology for a project.

query GetOntology { 
    project (where: {id: "<PROJECT_ID>"}) { 
        ontology { 
            normalized
            id 
        } 
    }
}

Clone an ontology

A cloned ontology is a copy of an existing ontology. Any changes made to the ontology will not affect the ontology it was cloned from. Note: Cloning ontologies from the legacy editor to the new editor is not supported.

Use the cloneOntology mutation to target the ontology by id and clone it.

mutation CloneOntologyFromProject {
    project (where: {id: "<PROJECT_ID>"}) {
        cloneOntology (ontologyId: "<TARGET_ONTOLOGY_ID>"){
            id
            name
        }
    }
}

Connect an ontology

Connecting an existing ontology is useful if you have multiple projects that must reference the same exact ontology. Any changes made to an ontology will affect all projects sharing that ontology. Note: Connecting ontologies from the legacy editor to the new editor is not supported.

Use the connectableOntologies query to list all ontologies that can be shared with a given project.

Then, use the connectOntology mutation to connect that ontology to your project.

query ConnectableOntologies {
    project (where: { id: "<PROJECT_ID>" }) {
        connectableOntologies {
            id
            name
        }
    }
}
mutation ConnectOntologyToProject {
    project (where: {id: "<PROJECT_ID>"}) {
        connectOntology (ontologyId: "<TARGET_ONTOLOGY_ID>"){
            id
            name
        }
    }
}

Rename an ontology

Use the update mutation to rename an ontology.

mutation RenameOntology {
    ontology (where: { id: "<ONTOLOGY_ID>" }) {
        update (data: {
            name: "<NEW_NAME>"
        }) {
            id
            name
        }
    }
}

Projects

Create a project

Use the createProject mutation to create a project.

mutation CreateProject {
    createProject (data: {
        name: "<PROJECT_NAME>"
    }){
        id
    }
}

Review

A Review is an assessment of a Label by a human reviewer.

Enable review step

Use the upsertReviewQueue mutation to enable the review step for a project and specify the percentage of assets that should be reviewed.

Field

Type

Description

quotaFactor

Float

A value between 0 and 1 that represents the percentage of asset from the project to review.

mutation UpsertReviewQueue (
    $projectId: ID!,
    $quotaFactor: Float!) {
    upsertReviewQueue (where: {
        project: {
            id: $projectId
        }
    },
     data: {quotaFactor: $quotaFactor}) {
        id
    }
}

Disable review step

Use the deleteReviewQueue mutation to disable the review step for a specific project.

mutation DeleteReviewQueue ($projectId: ID!) {
    deleteReviewQueue (where: {
        project: {
            id: $projectId
        }
    }) {
        id
    }
}

Webhooks

Use webhooks to set up a workflow to receive automatic notifications when an event happens in Labelbox. For a tutorial on setting up a simple webhooks workflow, see our tutorial on setting up Webhooks.

Create a webhook

Use the createWebhook mutation to create a webhook for a project.

Field

Type

Description

project.id

ID

Project ID

url

String

URL where Labelbox server should send notifications

secret

String

User-generated secret used for verification

topics.set

WebhookTopic

Values are:

LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED, REVIEW_CREATED, REVIEW_UPDATED, REVIEW_DELETED

mutation CreateWebhook {
    createWebhook (data:{
        project: {
            id:"<PROJECT_ID>"
        },
        url:"<HTTP_URL>",
        secret:"example_secret",
        topics: {
            set:[
                LABEL_CREATED,
                LABEL_UPDATED,
                LABEL_DELETED
            ]
        }
    }){
        id
    }
}

Update a webhook

After verifying and when entering production, use the updateWebhook mutation to update a specific webhook.

mutation UpdateWebhook {
    updateWebhook (where: {
        id:"<WEBHOOK_ID>"
    },
    data: {
        url:"<PRODUCTION_URL>"
    }){
        id
    }
}

Remove a webhook

Use the updateWebhook mutation to set the webhook status to INACTIVE.

Field

Type

Definition

status

WebhookStatus

Values are: ACTIVE, INACTIVE, REVOKED

mutation RemoveWebhook {
    updateWebhook (
        data: {
            status: INACTIVE
        }
        where: {
            id:"<WEBHOOK_ID>"
        }
    ){
        id
    }
}