---
title: "List projects"
method: GET
path: "/api/projects/"
tags: ["Projects"]
---

# List projects

`GET /api/projects/`

Retrieve a list of projects. Counter fields in each result follow one of two scopes:

* **Per-user progress** — computed for the authenticated user and their project role (for example `reviewed_number`, `review_total_tasks`, `queue_done`, `queue_total`, `queue_left`). These power project-card progress in the UI and differ across users. Note: `queue_left` counts manual review assignments only; when it is `0`, the card uses `review_total_tasks` / `reviewed_number` for auto-review progress.
* **Project-wide totals** — the same for every caller (for example `task_number`, `finished_task_number`).

For organization-level reviewed-task totals (all reviewers combined), use `GET /api/analytics/kpis/tasks_reviewed?projects={id}&tz=UTC` rather than `reviewed_number`. See Analytics KPI `tasks_reviewed`, `tasks_pending_review`, `annotated_tasks`, and `total_tasks` for other project-wide metrics.

## Query parameters

- `archived` boolean
- `filter` string
- `ids` string
- `include` string
- `members_limit` integer
- `ordering` string
- `page` integer
- `page_size` integer
- `search` string
- `source_interface_id` number
- `state` string
- `title` string
- `workspaces` number

## Response `200`

- PaginatedAllRolesProjectListList
  - `count` integer, required
  - `next` string, uri, nullable
  - `previous` string, uri, nullable
  - `results` AllRolesProjectList[], required
    - `agreement_methodology` 'consensus' | 'pairwise' — * `consensus` - Consensus * `pairwise` - Pairwise Averaging
    - `agreement_threshold` string, decimal, nullable — Agreement threshold
    - `allow_stream` boolean, required
    - `annotation_limit_count` integer, nullable — Limit by number of tasks
    - `annotation_limit_percent` string, decimal, nullable — Limit by percentage of tasks
    - `annotator_evaluation_continuous_tasks` integer — Continuous Evaluation: Required tasks
    - `annotator_evaluation_enabled` boolean — Evaluate all annotators against ground truth
    - `annotator_evaluation_metric` 'gt_agreement' | 'acceptance_score' | 'rejection_rate' — * `gt_agreement` - Ground truth agreement * `acceptance_score` - Acceptance score * `rejection_rate` - Rejection rate
    - `annotator_evaluation_minimum_score` string, decimal, nullable — Score required to pass evaluation
    - `annotator_evaluation_minimum_tasks` integer, nullable — Number of tasks for evaluation
    - `annotator_evaluation_onboarding_tasks` integer — Onboarding Evaluation: Required tasks
    - `assignment_settings` AssignmentSettings, required
      - `id` integer, required
      - `label_stream_task_distribution` 'auto_distribution' | 'assigned_only' — * `auto_distribution` - Label Stream distributes tasks automatically to annotators * `assigned_only` - Label Stream shows tasks only to assigned users
      - `project` integer, nullable
    - `blueprints` BlueprintList[], required
      - `created_at` string, date-time, required
      - `description` string, nullable — Project description
      - `id` integer, required
      - `share_id` string, required — base64 encoded id
      - `short_url` string, required
      - `task_count` integer, required
      - `title` string, nullable — Blueprint name. Must be between 3 and 50 characters long.
    - `color` string, nullable — Color
    - `comment_classification_config` string
    - `config_has_control_tags` boolean, required — Flag to detect is project ready for labeling
    - `config_suitable_for_bulk_annotation` boolean, required — Flag to detect is project ready for bulk annotation
    - `control_weights` object, nullable — Dict of weights for each control tag in metric calculation. Keys are control tag names from the labeling config. At least one tag must have a non-zero overall weight.
    - `created_at` string, date-time, required
    - `created_by` UserSimple — A ModelSerializer that takes additional arguments for "fields", "omit" and "expand" in order to control which fields are displayed, and whether to replace simple values with complex, nested serializations
      - `avatar` string, nullable, required
      - `email` string, email
      - `first_name` string
      - `id` integer, required
      - `last_name` string
      - `username` string, required
    - `custom_interface_code` string, nullable
    - `custom_interface_compiled` string, nullable
    - `custom_interface_params` unknown
    - `custom_script` string — Plugins
    - `custom_task_lock_ttl` integer, nullable — Task reservation time. TTL in seconds (UI displays and edits this value in minutes).
    - `data_types` object, nullable, required
    - `description` string, nullable — Description (Public)
    - `description_short` string, required
    - `duplication_done` boolean
    - `duplication_status` string
    - `enable_empty_annotation` boolean — Allow empty annotations
    - `evaluate_predictions_automatically` boolean — Retrieve and display predictions when loading a task
    - `expert_instruction` string, nullable — Instructions
    - `finished_task_number` integer, required — Project-wide count of tasks considered finished under project completion rules (agreement threshold, overlap, or FSM states such as needs-review and completed). Not a per-user queue counter. Analytics KPIs such as `annotated_tasks`, `done_tasks`, and `total_tasks` measure related but not identical project-wide totals.
    - `ground_truth_number` integer, required — Honeypot annotation number in project
    - `id` integer, required
    - `input_schema` unknown
    - `internal_description` unknown[], nullable, required — Description (Internal)
      - unknown
    - `internal_description_short` string, nullable, required
    - `is_dimensions_enabled` boolean, required
    - `is_draft` boolean — Whether or not the project is in the middle of being created
    - `is_published` boolean — Whether or not the project is published to annotators
    - `label_config` string, nullable — Labeling Configuration
    - `max_additional_annotators_assignable` integer, nullable — Maximum additional annotators
    - `maximum_annotations` integer — Annotations per task
    - `members` object[], required
    - `members_count` integer, required
    - `min_annotations_to_start_training` integer — Minimum number of completed tasks after which model training is started
    - `model_version` string, nullable — Machine learning model version
    - `num_tasks_with_annotations` integer, nullable, required — Tasks with at least one annotation. For annotators, counts only tasks this user annotated; for other roles, counts project-wide. For analytics, use annotated_tasks or related KPIs with explicit project/member filters.
    - `organization` integer, nullable
    - `output_schema` unknown
    - `overlap_cohort_percentage` integer — Annotations per task coverage
    - `parsed_label_config` object, required — JSON-formatted labeling configuration
    - `pause_on_failed_annotator_evaluation` boolean, nullable — Pause annotator on failed evaluation
    - `pinned_at` string, date-time, nullable — Pinned date and time
    - `prompts` object[], nullable, required
    - `queue_done` integer, required — Annotator-only: tasks this user has completed in the labeling queue for the project.
    - `queue_left` integer, nullable, required — Reviewer-only: remaining tasks in this user's manually assigned review queue. Returns 0 when no manual assignments apply; the project card then uses `review_total_tasks` and `reviewed_number` for auto-review progress. Not the same as the project-wide `tasks_pending_review` KPI.
    - `queue_total` integer, required — Role-dependent queue size. Annotators: total tasks in the labeling queue. Reviewers (list/counts): total manually assigned review tasks (same pool as `reviewer_queue_total`). Not the same as `task_number` (all project tasks) or `review_total_tasks` (auto-review stream pool).
    - `ready` boolean, required
    - `rejected` integer, required
    - `require_comment_on_skip` boolean — Require comment to skip
    - `reveal_preannotations_interactively` boolean — Reveal pre-annotations interactively
    - `review_settings` ReviewSettings, required
      - `annotator_batch_percent` string, decimal — Percent of an annotator’s work to review before moving to another annotator
      - `anonymize_annotations` boolean — Hide annotator names from annotations while review
      - `id` integer, required
      - `instruction` string, nullable — Instructions
      - `only_finished_tasks` boolean — Show only finished tasks in the review stream
      - `project` integer, nullable
      - `requeue_rejected_tasks_mode` 'requeue' | 'remove' | 'flexible' — * `requeue` - Requeue * `remove` - Remove * `flexible` - Flexible
      - `requeue_rejected_tasks_to_annotator` boolean, required
      - `require_comment_on_reject` boolean — Reviewers must leave a comment on reject
      - `review_criteria` 'all' | 'one' — * `all` - Task is reviewed if all annotations are reviewed * `one` - Task is reviewed if at least one annotation is reviewed
      - `review_only_manual_assignments` boolean — Show only manually assigned tasks in the review stream
      - `review_task_limit_percent` string, decimal, nullable — Task limit (%)
      - `sampling` 'task_id' | 'random' | 'by_annotator' — * `task_id` - By Task ID * `random` - Random * `by_annotator` - By Annotator
      - `show_agreement_to_reviewers` boolean — Show agreement to reviewers in the Data Manager
      - `show_data_manager_to_reviewers` boolean — Show the Data Manager to reviewers
      - `show_instruction` boolean — Show before reviewing
      - `show_unused_data_columns_to_reviewers` boolean, nullable — Show unused task data columns to reviewers in the Data Manager
    - `review_total_tasks` integer, nullable, required — Total tasks in this user's reviewer queue for the project (denominator for personal review progress). Respects review sampling limits when configured. Null for annotators. This is not the project-wide reviewed or pending count; see Analytics KPIs tasks_reviewed and tasks_pending_review for org-level totals.
    - `reviewed_number` integer, nullable, required — Tasks this user has reviewed in the project (personal reviewer progress shown on the project card). Includes only reviews created by the authenticated user, so the value can be lower than the project-wide reviewed total when multiple reviewers participate. Null for annotators. For all reviewed tasks in the project, use the Analytics KPI tasks_reviewed: GET /api/analytics/kpis/tasks_reviewed?projects={id}&tz=UTC.
    - `reviewer_queue_total` integer, nullable, required — Tasks manually assigned to this user for review (`reviewer_queue_total_count`). Null for annotators.
    - `sampling` 'Sequential sampling' | 'Uniform sampling' | 'Uncertainty sampling' — * `Sequential sampling` - Tasks are ordered by Data manager ordering * `Uniform sampling` - Tasks are chosen randomly * `Uncertainty sampling` - Tasks are chosen according to model uncertainty scores (active learning mode)
    - `show_annotation_history` boolean — Show Data Manager to Annotators
    - `show_collab_predictions` boolean — Use predictions to pre-label Tasks
    - `show_ground_truth_first` boolean — Onboarding mode (true): show ground truth tasks first in the labeling stream
    - `show_instruction` boolean — Show instructions before labeling
    - `show_overlap_first` boolean — Show tasks with overlap first
    - `show_skip_button` boolean — Allow skipping tasks
    - `show_unused_data_columns_to_annotators` boolean, nullable — Show only columns used in labeling configuration to Annotators. API uses inverse field semantics here: set false to show only used columns, set true to show all task.data columns.
    - `skip_queue` 'REQUEUE_FOR_ME' | 'REQUEUE_FOR_OTHERS' | 'IGNORE_SKIPPED' — * `REQUEUE_FOR_ME` - Requeue for me * `REQUEUE_FOR_OTHERS` - Requeue for others * `IGNORE_SKIPPED` - Ignore skipped
    - `skipped_annotations_number` integer, nullable, required
    - `source_interface_id` integer, nullable
    - `source_interface_version` integer, nullable — Stable version ID of the saved interface snapshot used by this project.
    - `start_training_on_annotation_update` boolean, required — Start model training after any annotations are submitted or updated
    - `state` string, required
    - `strict_task_overlap` boolean — Enforce strict overlap limit
    - `task_number` integer, required — Total task number in project
    - `title` string, nullable — Project Name
    - `total_annotations_number` integer, required
    - `total_predictions_number` integer, required
    - `use_custom_interface` boolean
    - `useful_annotation_number` integer, nullable, required
    - `workspace` integer, required
    - `workspace_title` string, nullable, required

## Changes

- **2026-08-07** `1b113b8df950` — 1 warning, 1 info
  - added the new `by_annotator` enum value to the `results/items/review_settings/sampling/allOf[#/components/schemas/ReviewSettingsSamplingEnum]/` response property for the response status `200`
  - added the optional property `results/items/review_settings/annotator_batch_percent` to the response with the `200` status
- **2026-07-28** `0bb2c2fc7ae2` — 1 info
  - added the optional property `results/items/annotator_evaluation_metric` to the response with the `200` status
- **2026-07-10** `32a5de4a180c` — 2 info
  - added the required property `results/items/internal_description` to the response with the `200` status
  - added the required property `results/items/internal_description_short` to the response with the `200` status
- **2026-07-08** `b5f055b9d45b` — 12 breaking
  - the response property `results/items/created_by/allOf[#/components/schemas/UserSimple]/avatar` became nullable for the status `200`
  - the response property `results/items/prompts` became nullable for the status `200`
  - the response property `results/items/skipped_annotations_number` became nullable for the status `200`
  - the response property `results/items/workspace_title` became nullable for the status `200`
  - …8 more
- …earlier changes not shown

[Full history](https://skmtc.dev/humansignal/apis/label-studio-api/changes/api/projects/get.md)

---

[API](https://skmtc.dev/humansignal/apis/label-studio-api.md) · [All operations](https://skmtc.dev/humansignal/apis/label-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/humansignal/label-studio-api/revisions/77d154d65462/schema)