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