---
title: "Import tasks"
method: POST
path: "/api/projects/{id}/import"
tags: ["Import"]
---

# Import tasks

`POST /api/projects/{id}/import`

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>

## Path parameters

- `id` integer, required

## Query parameters

- `commit_to_project` boolean
- `preannotated_from_fields` string[]
- `return_task_ids` boolean

## Request body

- ImportApiRequest[]
  - `allow_skip` boolean, nullable — Whether this task can be skipped. Set to False to make task unskippable.
  - `annotations` AnnotationRequest[]
    - `bulk_created` boolean, nullable — Annotation was created in bulk mode
    - `completed_by` integer
    - `draft_created_at` string, date-time, nullable — Draft creation time
    - `ground_truth` boolean — This annotation is a Ground Truth (ground_truth)
    - `import_id` integer, nullable — Original annotation ID that was at the import step or NULL if this annotation wasn't imported
    - `last_action` 'prediction' | 'propagated_annotation' | 'imported' | 'submitted' | 'updated' | 'skipped' | 'accepted' | 'rejected' | 'fixed_and_accepted' | 'deleted_review' — * `prediction` - Created from prediction * `propagated_annotation` - Created from another annotation * `imported` - Imported * `submitted` - Submitted * `updated` - Updated * `skipped` - Skipped * `accepted` - Accepted * `rejected` - Rejected * `fixed_and_accepted` - Fixed and accepted * `deleted_review` - Deleted review
    - `last_created_by` integer, nullable — User who created the last annotation history item
    - `lead_time` number, double, nullable — How much time it took to annotate the task
    - `parent_annotation` integer, nullable — Points to the parent annotation from which this annotation was created
    - `parent_prediction` integer, nullable — Points to the prediction from which this annotation was created
    - `project` integer, nullable — Project ID for this annotation
    - `result` object[] — List of annotation results for the task
    - `task` integer, nullable — Corresponding task for this annotation
    - `unique_id` string
    - `updated_by` integer, nullable — Last user who updated this annotation
    - `was_cancelled` boolean — User skipped the task
  - `cancelled_annotations` integer — Number of total cancelled annotations for the current task
  - `comment_authors` integer[] — Users who wrote comments
  - `comment_count` integer — Number of comments in the task including all annotations
  - `data` object, required — 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.
  - `file_upload` integer, nullable — Uploaded file used as data source for this task
  - `inner_id` integer, nullable — Internal task ID in the project, starts with 1
  - `last_comment_updated_at` string, date-time, nullable — When the last comment was updated
  - `meta` unknown
  - `overlap` integer — Number of distinct annotators that processed the current task
  - `precomputed_agreement` number, double, nullable — Average agreement score for the task
  - `predictions` PredictionRequest[]
    - `cluster` integer, nullable — Cluster for the current prediction
    - `mislabeling` number, double — Related task mislabeling score
    - `model` integer, nullable — An ML Backend instance that created the prediction.
    - `model_run` integer, nullable — A run of a ModelVersion that created the prediction.
    - `model_version` string — Model version - tag for predictions that can be used to filter tasks in Data Manager, as well as select specific model version for showing preannotations in the labeling interface
    - `neighbors` unknown
    - `project` integer, nullable
    - `result` object[], required — List of prediction results for the task
    - `score` number, double, nullable — Prediction score
    - `task` integer, required
  - `total_annotations` integer — Number of total annotations for the current task except cancelled annotations
  - `total_predictions` integer — Number of total predictions for the current task
  - `unresolved_comment_count` integer — Number of unresolved comments in the task including all annotations
  - `updated_by` integer, nullable — Last annotator or reviewer who updated this task

## Response `201`

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.

- object — Response format varies by edition. Non-Community editions return `{"import": <import_id>}` for async processing. Community edition returns the detailed response below with task counts.
  - `annotation_count` integer — Number of annotations added (Community edition sync import only)
  - `could_be_tasks_list` boolean — Whether uploaded files can contain lists of tasks, like CSV/TSV files (Community edition sync import only)
  - `data_columns` string[] — The list of found data columns (Community edition sync import only)
  - `duration` number — Time in seconds to create (Community edition sync import only)
  - `file_upload_ids` integer[] — Database IDs of uploaded files (Community edition sync import only)
  - `found_formats` string[] — The list of found file formats (Community edition sync import only)
  - `import` integer — Import ID for async operations (non-Community editions only). Use this ID to poll `/api/projects/{project_id}/imports/{import_id}` for status.
  - `predictions_count` integer — Number of predictions added (Community edition sync import only)
  - `task_count` integer — Number of tasks added (Community edition sync import only)

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/humansignal/apis/label-studio-api.md) · [All operations](https://skmtc.net/humansignal/apis/label-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humansignal/label-studio-api/versions/1b113b8df950/schema)