Import tasks | API Reference

Import data as labeling tasks in bulk using this API endpoint. You can use this API endpoint to import multiple tasks. One POST request is limited at 250K tasks and 200 MB.

Note: 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.

Async Import Behavior

For non-Community editions, this endpoint processes imports asynchronously.

The POST request can fail for invalid parameters, malformed request body, or other request-level validation errors.
However, data validation errors that occur during import processing are handled asynchronously and will not cause the POST request to fail.
Upon successful request validation, a response is returned: {"import": <import_id>}
Use the returned import_id to poll the GET /api/projects/{project_id}/imports/{import_id} endpoint to check the import status and see any data validation errors.
Data-level errors and import failures will only be visible in the GET request response.

For Community edition, imports are processed synchronously and return task counts immediately.

POST requests

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 'http://localhost:8000/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 'http://localhost:8000/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 'http://localhost:8000/api/projects/1/import' \
> --data '[{"url": "http://example.com/test1.csv"}, {"url": "http://example.com/test2.csv"}]'

Import data as labeling tasks in bulk using this API endpoint. You can use this API endpoint to import multiple tasks. One POST request is limited at 250K tasks and 200 MB. **Note:** 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. <br> ## Async Import Behavior <hr style="opacity:0.3"> **For non-Community editions, this endpoint processes imports asynchronously.** - The POST request **can fail** for invalid parameters, malformed request body, or other request-level validation errors. - However, **data validation errors** that occur during import processing are handled asynchronously and will not cause the POST request to fail. - Upon successful request validation, a response is returned: `{"import": <import_id>}` - Use the returned `import_id` to poll the GET `/api/projects/{project_id}/imports/{import_id}` endpoint to check the import status and see any data validation errors. - Data-level errors and import failures will only be visible in the GET request response. For Community edition, imports are processed synchronously and return task counts immediately. <br> ## POST requests <hr style="opacity:0.3"> 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. ```bash curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \ -X POST 'http://localhost:8000/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: ```bash curl -H 'Authorization: Token abc123' \ -X POST 'http://localhost:8000/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. ```bash curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \ -X POST 'http://localhost:8000/api/projects/1/import' \ --data '[{"url": "http://example.com/test1.csv"}, {"url": "http://example.com/test2.csv"}]' ``` <br>

Authentication

AuthorizationToken

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example:

curl https://label-studio-host/api/projects -H “Authorization: Token [your-token]”

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example: <br><pre><code class="language-bash">curl https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>

Path parameters

idintegerRequired

A unique integer value identifying this project.

Query parameters

commit_to_projectbooleanOptionalDefaults to true

Set to "true" to immediately commit tasks to the project.

preannotated_from_fieldslist of stringsOptional

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"].

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"]`.

return_task_idsbooleanOptionalDefaults to false

Set to "true" to return task IDs in the response.

Request

This endpoint expects a list of objects.

datamap from strings to anyRequired

User imported or uploaded data for a task. Data is formatted according to the project label config. You can find examples of data for your project on the Import page in the Label Studio Data Manager UI.

allow_skipboolean or nullOptional

Whether this task can be skipped. Set to False to make task unskippable.

annotationslist of objectsOptional

cancelled_annotationsintegerOptional-2147483648-2147483647

Number of total cancelled annotations for the current task

comment_authorslist of integersOptional

Users who wrote comments

comment_countintegerOptional-2147483648-2147483647

Number of comments in the task including all annotations

file_uploadinteger or nullOptional

Uploaded file used as data source for this task

inner_idlong or nullOptional-9223372036854776000-9223372036854776000

Internal task ID in the project, starts with 1

last_comment_updated_atdatetime or nullOptional

When the last comment was updated

metaany or nullOptional

Meta is user imported (uploaded) data and can be useful as input for an ML Backend for embeddings, advanced vectors, and other info. It is passed to ML during training/predicting steps.

overlapintegerOptional-2147483648-2147483647

Number of distinct annotators that processed the current task

precomputed_agreementdouble or nullOptional

Average agreement score for the task

predictionslist of objectsOptional

total_annotationsintegerOptional-2147483648-2147483647

Number of total annotations for the current task except cancelled annotations

total_predictionsintegerOptional-2147483648-2147483647

Number of total predictions for the current task

unresolved_comment_countintegerOptional-2147483648-2147483647

Number of unresolved comments in the task including all annotations

updated_byinteger or nullOptional

Last annotator or reviewer who updated this task

Response

Tasks successfully imported or import queued. For non-Community editions, the response will be {"import": <import_id>} which you can use to poll the import status. For Community edition, the response contains task counts and is processed synchronously.

annotation_countinteger

Number of annotations added (Community edition sync import only)

could_be_tasks_listboolean

Whether uploaded files can contain lists of tasks, like CSV/TSV files (Community edition sync import only)

data_columnslist of strings

The list of found data columns (Community edition sync import only)

durationdouble

Time in seconds to create (Community edition sync import only)

file_upload_idslist of integers

Database IDs of uploaded files (Community edition sync import only)

found_formatslist of strings

The list of found file formats (Community edition sync import only)

importinteger

Import ID for async operations (non-Community editions only). Use this ID to poll /api/projects/{project_id}/imports/{import_id} for status.

predictions_countinteger

Number of predictions added (Community edition sync import only)

task_countinteger

Number of tasks added (Community edition sync import only)

Errors

400

Bad Request Error