Supervisely
AboutAPI ReferenceSDK Reference
  • 🤖What's Supervisely
  • 🚀Ecosystem of Supervisely Apps
  • 💡FAQ
  • 📌Getting started
    • How to import
    • How to annotate
    • How to invite team members
    • How to connect agents
    • How to train models
  • 🔁Import and Export
    • Import
      • Overview
      • Import using Web UI
      • Supported annotation formats
        • Images
          • 🤖Supervisely JSON
          • 🤖Supervisely Blob
          • COCO
          • Yolo
          • Pascal VOC
          • Cityscapes
          • Images with PNG masks
          • Links from CSV, TXT and TSV
          • PDF files to images
          • Multiview images
          • Multispectral images
          • Medical 2D images
          • LabelMe
          • LabelStudio
          • Fisheye
          • High Color Depth
        • Videos
          • Supervisely
        • Pointclouds
          • Supervisely
          • .PCD, .PLY, .LAS, .LAZ pointclouds
          • Lyft
          • nuScenes
          • KITTI 3D
        • Pointcloud Episodes
          • Supervisely
          • .PCD, .PLY, .LAS, .LAZ pointclouds
          • Lyft
          • nuScenes
          • KITTI 360
        • Volumes
          • Supervisely
          • .NRRD, .DCM volumes
          • NIfTI
      • Import sample dataset
      • Import into an existing dataset
      • Import using Team Files
      • Import from Cloud
      • Import using API & SDK
      • Import using agent
    • Migrations
      • Roboflow to Supervisely
      • Labelbox to Supervisely
      • V7 to Supervisely
      • CVAT to Supervisely
    • Export
  • 📂Data Organization
    • Core concepts
    • MLOps Workflow
    • Projects
      • Datasets
      • Definitions
      • Collections
    • Team Files
    • Disk usage & Cleanup
    • Quality Assurance & Statistics
      • Practical applications of statistics
    • Operations with Data
      • Data Filtration
        • How to use advanced filters
      • Pipelines
      • Augmentations
      • Splitting data
      • Converting data
        • Convert to COCO
        • Convert to YOLO
        • Convert to Pascal VOC
    • Data Commander
      • Clone Project Meta
  • 📝Labeling
    • Labeling Toolboxes
      • Images
      • Videos 2.0
      • Videos 3.0
      • 3D Point Clouds
      • DICOM
      • Multiview images
      • Fisheye
    • Labeling Tools
      • Navigation & Selection Tools
      • Point Tool
      • Bounding Box (Rectangle) Tool
      • Polyline Tool
      • Polygon Tool
      • Brush Tool
      • Mask Pen Tool
      • Smart Tool
      • Graph (Keypoints) Tool
      • Frame-based tagging
    • Labeling Jobs
      • Labeling Queues
      • Labeling Consensus
      • Labeling Statistics
    • Labeling with AI-Assistance
  • 🤝Collaboration
    • Admin panel
      • Users management
      • Teams management
      • Server disk usage
      • Server trash bin
      • Server cleanup
      • Server stats and errors
    • Teams & workspaces
    • Members
    • Issues
    • Guides & exams
    • Activity log
    • Sharing
  • 🖥️Agents
    • Installation
      • Linux
      • Windows
      • AMI AWS
      • Kubernetes
    • How agents work
    • Restart and delete agents
    • Status and monitoring
    • Storage and cleanup
    • Integration with Docker
  • 🔮Neural Networks
    • Overview
    • Inference & Deployment
      • Overview
      • Supervisely Serving Apps
      • Deploy & Predict with Supervisely SDK
      • Using trained models outside of Supervisely
    • Model Evaluation Benchmark
      • Object Detection
      • Instance Segmentation
      • Semantic Segmentation
      • Custom Benchmark Integration
    • Custom Model Integration
      • Overview
      • Custom Inference
      • Custom Training
    • Legacy
      • Starting with Neural Networks
      • Train custom Neural Networks
      • Run pre-trained models
  • 👔Enterprise Edition
    • Get Supervisely
      • Installation
      • Post-installation
      • Upgrade
      • License Update
    • Kubernetes
      • Overview
      • Installation
      • Connect cluster
    • Advanced Tuning
      • HTTPS
      • Remote Storage
      • Single Sign-On (SSO)
      • CDN
      • Notifications
      • Moving Instance
      • Generating Troubleshoot Archive
      • Storage Cleanup
      • Private Apps
      • Data Folder
      • Firewall
      • HTTP Proxy
      • Offline usage
      • Multi-disk usage
      • Managed Postgres
      • Scalability Tuning
  • 🔧Customization and Integration
    • Supervisely .JSON Format
      • Project Structure
      • Project Meta: Classes, Tags, Settings
      • Tags
      • Objects
      • Single-Image Annotation
      • Single-Video Annotation
      • Point Cloud Episodes
      • Volumes Annotation
    • Developer Portal
    • SDK
    • API
  • 💡Resources
    • Changelog
    • GitHub
    • Blog
    • Ecosystem
Powered by GitBook
On this page
  • Key concepts
  • Step 1. Creating collection
  • 2. Adding items to collection
  • 3. Deleting items from collection
  • Annotating collections
  • Data filtering
  • Automating Collection Management with Python SDK
  • API support
  • Limitations

Was this helpful?

  1. Data Organization
  2. Projects

Collections

Collections are custom selections of data within a project. They enable flexible filtering and control over annotation workflows.

PreviousDefinitionsNextTeam Files

Last updated 15 days ago

Was this helpful?

Collections are custom groups of images, videos, or other items within a single Supervisely project. They serve as flexible selections of data, independent of dataset structure, and are often used for filtering, reviewing, or as a source for annotation queues.

Key concepts

  • A collection is always linked to a specific project.

  • Each collection contains only one data type — images, videos, or point clouds — consistent with the project type.

  • Collections are independent of datasets. A collection can include items from different datasets within the same project.

  • You can add or remove items from a collection at any time.

  • Internally, a collection is just a list of item IDs, along with a name and optional description.

Step 1. Creating collection

For creating collection open any dataset and switch to a flat list view like Gallery Expanded or Table Expanded at first.

  1. If you want to create collection from all dataset items do not select any items, just click the Arrow to the right of the Annotate button and select option Add to collection.

    If you want to create collection from several items, select the desired items using filters (1.1) or/and manual (1.2) selection and click the With (number) selected button and select option Add to collection (1.3).

  2. A modal window will appear. Give a name for new collection and press Add button.

    You can also add descriptions when creating a collection for better organization.

  3. From this moment, your newly created collection will be available in the list of collections.

Note: Creating or editing collections is available only in flat views. Dataset (hierarchical) view does not support this feature.

2. Adding items to collection

You can add items to an existing collection from any dataset inside one project. For example, let's go to a different dataset and:

  1. Select the desired items using filters (1.1) or/and manual (1.2) selection. Click the With (number) selected button and select option Add to collection (1.3).

  1. In the pop-up window, select an existing collection from the list and press Add button.

  1. Now, while in any dataset, you can select the desired collection from the filter bar, and you’ll see that you are taken directly to the selected collection.

3. Deleting items from collection

For deleting items from collection just select the desired items using filters (1) or manual selection (2). Click the With (number) selected button and select option Remove from collection (3).

Note: The Remove selected items option located above means deleting the items from the dataset where they were originally located.

Annotating collections

Collections provide a powerful way to organize and manage subsets of data across different datasets. Once you’ve grouped items into a collection, you can send them for annotation with full flexibility and control.

There are two main ways to annotate collections:

1. Direct annotation inside the collection:

Open a collection, browse through items, and annotate them just like in any regular dataset. All changes will be saved directly to the original dataset the item belongs to.

2. Labeling Queue source

Create a Labeling Queue based on a collection: Use a collection as the data source when setting up a Labeling Queue. This allows you to assign specific items from the collection to annotation teams or individuals.

Collections maintain a dynamic link to their items. Any annotations made within a collection are instantly reflected in the dataset of origin.

For example, to create a Labeling Queue based on an existing Collection:

  1. Go to Labeling Job from the main menu,

  2. Select the Queue tab,

  3. In the Data to Annotate section, choose Collection as the source and then select the specific collection you want to use.

You can create a queue with Collection as the source, and later add the desired items to it.

Example workflow:

  1. Create an empty collection inside a new or existing project.

  2. Create a Labeling Queue that pulls data from this collection.

  3. As you import new data or identify specific items for annotation, add them to the collection.

  4. The queue will automatically reflect the collection's contents.

This setup allows dynamic control over labeling pipelines, especially useful when data arrives in batches or needs manual pre-selection.

Note: Collections do not duplicate data — they act as smart references to existing items across multiple datasets.

Data filtering

Collections are ideal for creating reusable subsets of data. For example, after training a model, you might group all false positives into a collection for further analysis or re-labeling.

Benefits:

  • Simplifies repeated access to specific groups of items

  • No need to store or pass item ID lists in code

  • Easily maintain and update the selection over time

Automating Collection Management with Python SDK

import supervisely as sly

api = sly.Api()

new = api.entity_collections.create(
    project_id=project_id,
    name="my collection",
    description="my collection description",
)
print(new.id)
# Output: 123
import supervisely as sly

api = sly.Api()

collection_id = 2
info = api.entities_collection.get_info_by_id(collection_id)
print(info.name)
# Output: my collection
import supervisely as sly

api = sly.Api()

project_id = 1
collections = api.entities_collection.get_list(project_id)
for collection in collections:
    print(collection.name)
# Output: ["my collection", "another collection"]
import supervisely as sly

api = sly.Api()

collection_id = 2
item_ids = [525, 526]
res = api.entities_collection.add_items(collection_id, item_ids)
print(res)
# Output: [
#   {"id": 1, "entityId": 525, 'createdAt': '2025-04-10T08:49:41.852Z'},
#   {"id": 2, "entityId": 526, 'createdAt': '2025-04-10T08:49:41.852Z'}
# ]
import supervisely as sly

api = sly.Api()

collection_id = 123
project_id = 111
res = api.entities_collection.get_items(collection_id, project_id)
print(res)
# Output: [
#   ImageInfo(id=525, name='image1.jpg', ...),
#   ImageInfo(id=526, name='image2.jpg', ...)
# ]
import supervisely as sly

api = sly.Api()

collection_id = 2
item_ids = [525, 526, 527]
res = api.entities_collection.remove_items(collection_id, item_ids)
# print(res)
# Output: [{"id": 1, "entityId": 525}, {"id": 2, "entityId": 526}]
import supervisely as sly

api = sly.Api()

collection_id = 2
api.entities_collection.remove(collection_id)

You can also use Collections to create a Labeling Queue programmatically. This allows you to automate the process of labeling data based on specific collections. Adding new items to a collection will automatically update the Labeling Queue, allowing for dynamic management of your annotation tasks.

Here's a simple example of how to integrate collections into your labeling workflow:

Script 1 creates a collection and adds items to it. The second script checks the queue stats, retrieves items that finished labeling and removes them from the collection (for example, if you want to move them to another project or collection).

Script 1 (create Collection and Labeling Queue)
import random
import supervisely as sly

api = sly.Api()

project_id = 1

all_images = api.image.get_list(project_id=project_id)

# let's choose 10 random images
random_images = random.sample(all_images, 10)

# create a collection
collection = api.entity_collections.create(
    project_id=project_id,
    name="Collection 1 for labeling",
)
print(f"Collection created: {collection.id}")

# get my info
me = api.users.get_my_info()

# create a labeling queue
queue = api.labeling_queue.create(
    collection_id=collection.id,
    name="Labeling Queue 1",
    user_ids=[me.id],
    reviewer_ids=[me.id],
    dynamic_classes=True,
    dynamic_tags=True,
    allow_review_own_annotations=True,
    skip_complete_job_on_empty=True,
)
print(f"Labeling queue created: {queue.id}")

# collection is empty, let's add items
item_ids = [image.id for image in random_images]
api.entities_collection.add_items(
    collection_id=collection.id,
    item_ids=item_ids,
)

# after
python script1.py
Script 2 (get labeled items and remove them from collection)
import supervisely as sly
import time

api = sly.Api()

project_id = 1
collection_id = 2
queue_id = 3

res = api.labeling_queue.get_entities_all_pages(
    queue_id,
    collection_id,
    status="accepted",
)
images = res["images"]
img_ids = [i["id"] for i in images]

# create a new collection
new_collection = api.entity_collections.create(
    project_id=project_id,
    name="Collection 2 for training",
)
print(f"Collection created: {new_collection.id}")

# add items to the new collection
api.entities_collection.add_items(
    collection_id=new_collection.id,
    item_ids=img_ids,
)
# remove items from the old collection
api.entities_collection.remove_items(
    collection_id=collection_id,
    item_ids=img_ids,
)
python script2.py

API support

Limitations

  • Collections are limited to a single project.

  • Only one data type per collection is supported.

  • There’s currently no dedicated collections page — access and management is done through flat views or Labeling Queue creation.

Learn how to programmatically create, retrieve, and manage collections using the Supervisely Python SDK. The following examples provide step-by-step guidance for efficient collection handling. Check out the for more details.

Collections are fully accessible through the Supervisely API. With these , you can:

📂
SDK Reference
Entity Collections
Add Items to Entities Collection
Create Entities Collection
Get Entities Collection info by ID
List Entities Collections
Remove Entities Collection
Remove Items From Entities Collection
Update Entities Collection