Python API · Kili Docs

Table of contents

append_many_to_dataset
append_to_labels
append_to_roles
assets
count_assets
count_projects
create_empty_project
create_honeypot
create_organization
create_predictions
create_user
create_user_from_email_if_not_exists
delete_from_roles
delete_many_from_dataset
export_labels_as_df
force_project_kpis
label_created_or_updated
labels
organizations
parse_json_response_for_multi_classification
parse_json_response_for_single_classification
project_users
projects
reset_password
signin
update_password
update_project
update_properties_in_asset
update_properties_in_label
update_properties_in_organization
update_properties_in_project
update_properties_in_project_user
update_properties_in_role
update_properties_in_user
users

`append_many_to_dataset`

Append assets to a project

Parameters :

project_id : str
Identifier of the project
content_array : list of str
List of elements added to the assets of the project
- For a NLP project, the content is directly in text format
- For an Image / Video / Pdf project, the content must be hosted on a web server,
  and you point Kili to your data by giving the URLs
external_id_array : list of str
List of external ids given to identify the assets
is_honeypot_array : list of bool, optional (default = None)
status_array : list of str, optional (default = None)
By default, all imported assets are set to 'TODO'. It can also be set to
'ONGOING', 'LABELED', 'REVIEWED'
json_metadata_array : list of dict , optional (default = None)
The metadata given to each asset should be stored in a json like dict.

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`append_to_labels`

Append a label to labels

Parameters :

author_id : str
Email of the author of the label
json_response : dict
Label is given here
label_asset_id : str
Identifier of the asset
label_type : str
Can be one of {'AUTOSAVE', 'DEFAULT', 'PREDICTION', 'REVIEW'}
seconds_to_label : int
skipped : bool, optional (default = False)

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`append_to_roles`

Add a user to a project

If the user does not exist in your organization, he is invited and added both to your organization and project. This function can also be used to change the role of the user in the project.

Parameters :

project_id : str
Id of the project.
user_email : str
The email of the user. This email is used as the unique identifier of the user.
role : str
One of {"ADMIN", "REVIEWER", "LABELER", "READER"}.

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`assets`

Get an array of assets from a project

Parameters :

project_id : str
Identifier of the project.
skip : int, optional (default = None)
Number of assets to skip (they are ordered by their date of creation, first to last).
fields : list of string, optional (default = ['id', 'content', 'externalId', 'isHoneypot', 'isUsedForConsensus', 'jsonMetadata', 'labels.author.id', 'labels.author.email','labels.jsonResponse', 'labels.skipped', 'priority', 'projects.id', 'projects.title', 'project.jsonInterface'])
All the fields to request among the possible fields for the assets, default for None are the non-calculated fields)
Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#asset
first : int, optional (default = None)
Maximum number of assets to return. Can only be between 0 and 100.
consensus_mark_gt : float, optional (default = None)
Minimum amout of consensus for the asset.
consensus_mark_lt : float, optional (default = None)
Maximum amout of consensus for the asset.
external_id_contains : list of str, optional (default = None)
Returned assets should have an external id that belongs to that list, if given.
honeypot_mark_gt : float, optional (default = None)
Minimum amout of honeypot for the asset.
honeypot_mark_lt : float, optional (default = None)
Maximum amout of honeypot for the asset.
status_in : list of str, optional (default = None)
Returned assets should have a status that belongs to that list, if given.
Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
label_type_in : list of str, optional (default = None)
Returned assets should have a label whose type belongs to that list, if given.
label_author_in : list of str, optional (default = None)
Returned assets should have a label whose status belongs to that list, if given.
label_consensus_mark_gt, optional (default = None)
Returned assets should have a label whose consensus is greater than this number.
label_consensus_mark_lt : float, optional (default = None)
Returned assets should have a label whose consensus is lower than this number.
label_created_at : string, optional (default = None)
Returned assets should have a label whose creation date is equal to this date.
Formatted string should have format : "YYYY-MM-DD"
label_created_at_gt : string, optional (default = None)
Returned assets should have a label whose creation date is greater than this date.
Formatted string should have format : "YYYY-MM-DD"
label_created_at_lt : string, optional (default = None)
Returned assets should have a label whose creation date is lower than this date.
Formatted string should have format : "YYYY-MM-DD"
label_json_response_contains : list of str, optional (default = None)
Returned assets should have a substring of the label's jsonResponse that belongs to that list, if given.
label_honeypot_mark_gt : float, optional (default = None)
Returned assets should have a label whose honeypot is greater than this number.
label_honeypot_mark_lt : float, optional (default = None)
Returned assets should have a label whose honeypot is lower than this number.
label_skipped : bool, optional (default = None)
Returned assets should have a label which is skipped
format : str, optional (default = None)
If equal to 'pandas', returns a pandas DataFrame
disable_tqdm : bool, optional (default = False)

Returns :

a result object which contains the query if it was successful, or an error message else.

`count_assets`

Count and return the number of assets with the given parameters

Parameters beginning with 'label_' apply to labels, others apply to assets.

Parameters :

asset_id : str
Identifier of the asset
project_id : str
Identifier of the project
external_id_contains : list of str, optional (default = None)
Returned assets should have an external id that belongs to that list, if given.
status_in : list of str, optional (default = None)
Returned assets should have a status that belongs to that list, if given.
Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
consensus_mark_gt : float, optional (default = None)
Minimum amout of consensus for the asset.
consensus_mark_lt : float, optional (default = None)
Maximum amout of consensus for the asset.
honeypot_mark_gt : float, optional (default = None)
Minimum amout of honeypot for the asset.
honeypot_mark_lt : float, optional (default = None)
Maximum amout of consensus for the asset.
label_type_in : list of str, optional (default = None)
Returned assets should have a label whose type belongs to that list, if given.
label_author_in : list of str, optional (default = None)
Returned assets should have a label whose status belongs to that list, if given.
label_consensus_mark_gt : float, optional (default = None)
Returned assets should have a label whose consensus is greater than this number.
label_consensus_mark_lt : float, optional (default = None)
Returned assets should have a label whose consensus is lower than this number.
label_created_at : string, optional (default = None)
Returned assets should have a label whose creation date is equal to this date.
Formatted string should have format : "YYYY-MM-DD"
label_created_at_gt : string, optional (default = None)
Returned assets should have a label whose creation date is greater than this date.
Formatted string should have format : "YYYY-MM-DD"
label_created_at_lt : string, optional (default = None)
Returned assets should have a label whose creation date is lower than this date.
Formatted string should have format : "YYYY-MM-DD"
label_honeypot_mark_gt : float, optional (default = None)
Returned assets should have a label whose honeypot is greater than this number.
label_honeypot_mark_lt : float, optional (default = None)
Returned assets should have a label whose honeypot is lower than this number.
label_json_response_contains : list of str, optional (default = None)
Returned assets should have a substring of the label's jsonResponse that belongs to that list, if given.
label_skipped : bool, optional (default = None)
Returned assets should have a label which is skipped

Returns :

a result object which contains the query if it was successful, or an error message else.

`count_projects`

Counts the number of projects with a search_query

Parameters :

project_id : str, optional (default = None)
Select a specific project through its project_id
search_query : str, optional (default = None)
Returned projects have a title or a description that matches this string.

Returns :

a positive integer corresponding to the number of results of the query if it was successful, or an error message else.

`create_empty_project`

Create an empty project

Parameters :

user_id : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`create_honeypot`

Create honeypot for a label

Parameters :

asset_id : str
Identifier of the asset
json_response : dict
The honeypot label of the asset

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`create_organization`

Create an organization

Each user must be linked to an organization

Parameters :

name : str
address : str
zip_code : str
city : str
country : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`create_predictions`

Create predictions for some assets

Parameters :

project_id : str
external_id_array : list of str
The external identifiers of the assets for which we want to add predictions
model_name_array : list of str
In case you want to precise from which model the label originated
json_response_array : list of dict
The predictions are given here. An example can be found here, for a polygon

{    
    "JOB_0": {    
        "annotations": [    
            {    
                "categories": [{ "name": "OBJECT_B", "confidence": 100 }],    
                "boundingPoly": [    
                    {    
                        "normalizedVertices": [    
                            { "x": 0.07, "y": 0.88 },    
                            { "x": 0.07, "y": 0.32 },    
                            { "x": 0.94, "y": 0.32 },    
                            { "x": 0.94, "y": 0.88 }    
                        ]    
                    }    
                ]    
            }    
        ]    
    }    
}

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`create_user`

Add a user to your organization.

Parameters :

name : str
Name of the new user.
email : str
Email of the new user, used as his unique identifier.
password : str
On the first sign in, he will use this password and be able to change it.
organization_role : str
One of "ADMIN", "USER".

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`create_user_from_email_if_not_exists`

Create a user for a given project

Parameters :

name : str
email : str
organization_role : str
One of "ADMIN", "REVIEWER", "LABELER", "READER"
project_id : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`delete_from_roles`

Delete users by their role_id

Parameters :

role_id : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`delete_many_from_dataset`

Delete assets from a project

Parameters :

asset_ids : list of str
The list of identifiers of the assets to delete.

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`export_labels_as_df`

Get the labels of a project as a pandas DataFrame

Parameters :

project_id : str
fields : list of string, optional (default = [ 'author.email', 'author.id','author.name', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'])
All the fields to request among the possible fields for the labels, default are the non-calculated fields)
- Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#label Returns :
labels_df : pandas DataFrame containing the labels.

`force_project_kpis`

Compute KPIs for a project

Parameters :

project_id : str

Returns :

None

`label_created_or_updated`

Subscribe a callback to a project, which is executed when a label is created or updated

Parameters :

project_id : str
callback : function of (str, str) -> None
This function takes as input the id of the asset and its content.

Returns :

None

`labels`

Get an array of labels from a project

Parameters :

asset_id : str
Identifier of the asset.
asset_status_in : list of str, optional (default = None)
Returned labels should have a status that belongs to that list, if given.
Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
asset_external_id_in : list of str, optional (default = None)
Returned labels should have an external id that belongs to that list, if given.
author_in : list of str, optional (default = None)
Returned labels should have a label whose status belongs to that list, if given.
created_at : string, optional (default = None)
Returned labels should have a label whose creation date is equal to this date.
Formatted string should have format : "YYYY-MM-DD"
created_at_gt : string, optional (default = None)
Returned labels should have a label whose creation date is greater than this date.
Formatted string should have format : "YYYY-MM-DD"
created_at_lt : string, optional (default = None)
Returned labels should have a label whose creation date is lower than this date.
Formatted string should have format : "YYYY-MM-DD"
fields : list of string, optional (default = ['author.email', 'author.id','author.name', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'])
All the fields to request among the possible fields for the labels, default for None are the non-calculated fields)
Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#label
first : int, optional (default = None)
Maximum number of labels to return. Can only be between 0 and 100.
honeypot_mark_gt : float, optional (default = None)
Returned labels should have a label whose honeypot is greater than this number.
honeypot_mark_lt : float, optional (default = None)
Returned labels should have a label whose honeypot is lower than this number.
json_response_contains : list of str, optional (default = None)
Returned labels should have a substring of the jsonResponse that belongs to that list, if given.
label_id : str
Identifier of the label.
project_id : str
Identifier of the project.
skip : int, optional (default = None)
Number of labels to skip (they are ordered by their date of creation, first to last).
skipped : bool, optional (default = None)
Returned labels should have a label which is skipped
type_in : list of str, optional (default = None)
Returned labels should have a label whose type belongs to that list, if given.
user_id : str
Identifier of the user.

Returns :

a result object which contains the query if it was successful, or an error message else.

`organizations`

Get organizations

Returns users whose email / organization id correspond to the given ones.

Parameters :

email : str, optional (default = None)
organization_id : str, optional (default = None)
fields : list of string, optional (default = ['id', 'name'])
All the fields to request among the possible fields for the organizations, default for None are the non-calculated fields)
Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#organization
first : int, optional (default = 100)
Maximum number of organizations to return
skip : int, optional (default = 0)
Number of skipped organizations (they are ordered by creation date)

Returns :

a result object which contains the query if it was successful, or an error message else.

`parse_json_response_for_multi_classification`

Get the names of categories from a json_response, for a multi class - classification task

`parse_json_response_for_single_classification`

Get the names of categories from a json_response, for a single class - classification task

`project_users`

Return projects and their users (possibly with their KPIs)

Parameters :

email : str, optional (default = None)
organization_id : str, optional (default = None)
project_id : str, optional (default = None)
fields : list, optional (default = ['activated', 'id', 'role', 'starred', 'user.email', 'user.id', 'user.name'])
All the fields to request among the possible fields for the projectUsers, default for None are the non-calculated fields)
Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#projectuser
first : int, optional (default = 100)
Maximum number of users to return. Can only be between 0 and 100.
skip : int, optional (default = 0)
Number of project users to skip
with_kpis : bool, optional (default = False)
Whether or not to compute kpis

Returns :

a result object which contains the query if it was successful, or an error message else.

`projects`

Get projects with a search_query

Parameters :

project_id : str, optional (default = None)
Select a specific project through its project_id
search_query : str, optional (default = None)
Returned projects have a title or a description that matches this string.
skip : int, optional (default = 0)
Number of projects to skip (they are ordered by their creation)
fields : list of string, optional (default = ['consensusTotCoverage', 'id', 'inputType', 'interfaceCategory', 'jsonInterface', 'maxWorkerCount', 'minAgreement', 'minConsensusSize', 'roles.id', 'roles.role', 'roles.user.email', 'roles.user.id', 'roles.user.name', 'title'])
All the fields to request among the possible fields for the projects, default for None are the non-calculated fields)
Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#project
first : int , optional (default = 100)
Maximum number of projects to return. Can only be between 0 and 100.

Returns :

a result object which contains the query if it was successful, or an error message else.

`reset_password`

Reset password

Parameters :

email : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`signin`

Parameters :

email : str
password : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_password`

Update password

Parameters :

email : str
old_password : str
new_password_1 : str
new_password_2 : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_project`

Update a project

Parameters :

project_id : str
title : str
description : str
interface_category : str
Currently, one of
{IV2, ALL, CLASSIFICATION, SENTIMENT, NER, NER_WITH_RELATIONS,
RELATION_EXTRACTION, ENTITY_GROUPING, COREFERENCE_RESOLUTION,
TRANSLATION, TRANSCRIPTION, IMAGE, MULTICLASS_IMAGE, CUSTOM,
IMAGE_TO_GRAPH, IMAGE_WITH_SEARCH, IMAGE_TO_TEXT, MULTICLASS_TEXT_CLASSIFICATION,
SINGLECLASS_TEXT_CLASSIFICATION, MULTICLASS_IMAGE_CLASSIFICATION,
SINGLECLASS_IMAGE_CLASSIFICATION, VIDEO_CLASSIFICATION, NA}
input_type : str, optional (default = 'TEXT')
Currently, one of {AUDIO, IMAGE, PDF, TEXT, URL, VIDEO, NA}
consensus_tot_coverage : int, optional (default = 0)
Should be between 0 and 100. It is the percentage of the dataset
that will be annotated several times.
min_consensus_size : int, optional (default = 1)
Number of people that will annotate the same asset, for consensus computation.
max_worker_count : int, optional (default = 4)
Maximum number of workers in the project
min_agreement : int, optional (default = 66)
Should be a percentage (between 0 and 100)
use_honey_pot : bool, optional (default = False)
Whether to compute honeypot in the project
instructions : str, optional (default = None)
You can give instructions, they will be available to the annotators during the labeling process. Returns :
a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_asset`

Update the properties of one asset

Parameters :

asset_id : str
The id of the asset to delete
external_id : str, optional (default = None)
If given, the asset identified by this external identifier will be modified.
priority : int, optional (default = None)
By default, all assets have a priority of 0
json_metadata : dict (default = None)
Update the metadata of the asset with a json like dict.
consensus_mark : float (default = None)
Should be between 0 and 1
honeypot_mark : float (default = None)
Should be between 0 and 1
to_be_labeled_by : list of str (default = None)
If given, should contain the emails of the labelers authorized to label the asset
content : str (default = None)
- For a NLP project, the content is directly in text format
- For an Image / Video / Pdf project, the content must be hosted on a web server,
  and you point Kili to your data by giving the URLs
status : str (default = None)
Should be in {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
is_used_for_consensus : bool (default = None)
Whether to use the asset to compute consensus kpis or not
is_honeypot : bool (default = None)
Whether to use the asset for honeypot

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_label`

Update properties of a label

Parameters :

label_id : str
Identifier of the label
seconds_to_label : int, optional (default = None)
model_name : str, optional (default = None)
json_response : dict, optional (default = None)
The label is given here

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_organization`

Modify an organization

Parameters :

organization_id : str
name : str
address : str
zip_code : str
city : str
country : str

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_project`

Update properties of a project

Parameters :

project_id : str
Identifier of the project
consensus_mark : float, optional (default = None)
Should be between 0 and 1
consensus_tot_coverage : int, optional (default = None)
Should be between 0 and 100. It is the percentage of the dataset
that will be annotated several times.
description : str, optional (default = None)
honeypot_mark : float, optional (default = None)
Should be between 0 and 1
instructions : str, optional (default = None)
interface_category : str, optional (default = 'IV2')
Always use 'IV2'
input_type : str, optional (default = None)
Currently, one of {AUDIO, IMAGE, PDF, TEXT, URL, VIDEO, NA}
json_interface : dict, optional (default = None)
The json parameters of the project, see Edit your interface.
min_consensus_size : int, optional (default = None)
Number of people that will annotate the same asset, for consensus computation.
number_of_assets : int, optional (default = None)
Defaults to 0
number_of_assets_with_empty_labels : int, optional (default = None)
Defaults to 0
number_of_remaining_assets : int, optional (default = None)
Defaults to 0
number_of_reviewed_assets : int, optional (default = None)
Defaults to 0
title : str, optional (default = None)

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_project_user`

Update properties of a project-user tuple

Parameters :

project_user_id : str
consensus_mark : float, optional (default = None)
Should be between 0 and 1.
honeypot_mark : float, optional (default = None)
Should be between 0 and 1.
json_interface : dict, optional (default = None)
The json parameters of the project, see Edit your interface.
number_of_labeled_assets : int, optional (default = None)
Number of assets the user labeled in the project.
total_duration : int, optional (default = None)
Total time the user spent in the project.

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_role`

Update properties of a role

You should be either an admin or a reviewer of the project, or an admin of the organization to be able to change the role of somebody.

Parameters :

role_id : str
Role identifier of the user. E.g. : 'to-be-deactivated'
project_id : str
Identifier of the project
user_id : str
The email or identifier of the user with updated role
role : str
The new role. One of "ADMIN", "REVIEWER", "LABELER", "READER"

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`update_properties_in_user`

Update the properties of a user

Parameters :

email : str
The email is the identifier of the user
name : str, optional (default = None)
organization_id : str, optional (default = None)
Change the organization the user is related to.
organization_role : str, optional (default = None)
Change the role of the user. One of "ADMIN", "REVIEWER", "LABELER", "READER".
activated : bool, optional (default = None)
In case we want to deactivate a user, but keep it.

Returns :

a result object which indicates if the mutation was successful, or an error message else.

`users`

Get users

Returns users whose email / organization id correspond to the given ones.

Parameters :

email : str, optional (default = None)
organization_id : str, optional (default = None)
fields : list of string, optional (default = ['email', 'id', 'name'])
All the fields to request among the possible fields for the users, default for None are the non-calculated fields)
Possible fields : see https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#user
first : int, optional (default = 100)
Maximum number of users to return. Can only be between 0 and 100.
skip : int, optional (default = 0)
Number of skipped users (they are ordered by creation date)

Returns :

a result object which contains the query if it was successful, or an error message else.