Projects

Import tasks

POST

Use this API endpoint to import labeling tasks in bulk. Note that each POST request is limited at 250K tasks and 200 MB. The project ID can be found in the URL when viewing the project in Label Studio, or you can retrieve all project IDs using List all projects.

Imported data is verified against a project label_config and must include all variables that were used in the label_config.

For example, if the label configuration has a $text variable, then each item in a data object must include a text field.

There are three possible ways to import tasks with this endpoint:

1. POST with data

Send JSON tasks as POST data. Only JSON is supported for POSTing files directly.

Update this example to specify your authorization token and Label Studio instance host, then run the following from the command line:

$curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \
>-X POST 'https://localhost:8080/api/projects/1/import' --data '[{"text": "Some text 1"}, {"text": "Some text 2"}]'

2. POST with files

Send tasks as files. You can attach multiple files with different names.

  • JSON: text files in JavaScript object notation format
  • CSV: text files with tables in Comma Separated Values format
  • TSV: text files with tables in Tab Separated Value format
  • TXT: simple text files are similar to CSV with one column and no header, supported for projects with one source only

Update this example to specify your authorization token, Label Studio instance host, and file name and path, then run the following from the command line:

$curl -H 'Authorization: Token abc123' \
>-X POST 'https://localhost:8080/api/projects/1/import' -F ‘file=@path/to/my_file.csv’

3. POST with URL

You can also provide a URL to a file with labeling tasks. Supported file formats are the same as in option 2.

$curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \
>-X POST 'https://localhost:8080/api/projects/1/import' \
>--data '[{"url": "http://example.com/test1.csv"}, {"url": "http://example.com/test2.csv"}]'

Path parameters

idintegerRequired
A unique integer value identifying this project.

Query parameters

commit_to_projectbooleanOptional
Set to "true" to immediately commit tasks to the project.
return_task_idsbooleanOptional
Set to "true" to return task IDs in the response.
preannotated_from_fieldsstringOptional

List of fields to preannotate from the task data. For example, if you provide a list of {"text": "text", "prediction": "label"} items in the request, the system will create a task with the text field and a prediction with the label field when preannoted_from_fields=["prediction"].

Request

This endpoint expects a list of maps from strings to any.

Response

This endpoint returns an object
task_count
integerOptional
Number of tasks added
annotation_count
integerOptional
Number of annotations added
predictions_count
integerOptional
Number of predictions added
duration
doubleOptional
Time in seconds to create
file_upload_ids
list of integersOptional
Database IDs of uploaded files
could_be_tasks_list
booleanOptional
Whether uploaded files can contain lists of tasks, like CSV/TSV files
found_formats
list of stringsOptional
The list of found file formats
data_columns
list of stringsOptional
The list of found data columns
POST
1curl -X POST http://localhost:8080/api/projects/1/import \
2 -H "Authorization: Token <api_key>" \
3 -H "Content-Type: application/json" \
4 -d '[
5 {}
6]'
200Successful
1{
2 "task_count": 1,
3 "annotation_count": 1,
4 "predictions_count": 1,
5 "duration": 1.1,
6 "file_upload_ids": [
7 1
8 ],
9 "could_be_tasks_list": true,
10 "found_formats": [
11 "found_formats"
12 ],
13 "data_columns": [
14 "data_columns"
15 ]
16}