Subscribe to release notesStatus pageCommunity

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>"}) { 
        secondsToLabel
        secondsToReview
        secondsToCreate
    }
}
FieldTypeDescription
secondsToLabelFloatIs a deprecated value and should be ignored.
secondsToReviewFloatLogs the seconds that any other labeler, reviewer, or admin spends in the Editor for a given Label after it has been submitted.
secondsToCreateFloatLogs the seconds that the original labeler spends in the Editor for a given label. If this user goes back into a label, it adds to this value.

Get JSON label by project

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

ArgumentTypeDescription
firstPageSizeNumber of elements in the paginated result
skipIntNumber 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.

ArgumentTypeDescription
firstPageSizeNumber of elements in the paginated result
skipIntNumber 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:

FieldTypeDescription
downloadUrlStringURL 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.
createdAtStringTimestamp indicating when the export was generated
shouldPollBooleanIf 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.

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