EntitiesCollectionApi¶

class EntitiesCollectionApi[source]¶

Bases: supervisely.api.module_api.UpdateableModule, supervisely.api.module_api.RemoveableModuleApi

API for working with Entities Collection. EntitiesCollectionApi object is immutable.

Parameters

api : Api: API connection to the server.

Usage example

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervisely.com", token="4r47N...xaTatb")

collection = api.entities_collection.get_list(9) # api usage example

Methods

`add_items`	Add items to Entities Collection.
`convert_info_to_json`	_convert_info_to_json
`create`	Creates Entities Collections.
`exists`	Checks if an entity with the given parent_id and name exists
`get_free_name`	Generates a free name for an entity with the given parent_id and name.
`get_info_by_ai_search_key`	Get information about Entities Collection of type `CollectionType.AI_SEARCH` with given AI search key.
`get_info_by_id`	Get information about Entities Collection with given ID.
`get_info_by_name`	Get information about an entity by its name from the Supervisely server.
`get_items`	Get items from Entities Collection.
`get_list`	Get list of information about Entities Collection for the given project.
`get_list_all_pages`	Get list of all or limited quantity entities from the Supervisely server.
`get_list_all_pages_generator`	This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved
`get_list_idx_page_async`	Get the list of items for a given page number.
`get_list_page_generator_async`	Yields list of images in dataset asynchronously page by page.
`info_sequence`	NamedTuple EntitiesCollectionInfo information about Entities Collection.
`info_tuple_name`	Get string name of `EntitiesCollectionInfo` NamedTuple.
`remove`	Remove Entites Collection with the specified ID from the Supervisely server.
`remove_batch`	Remove entities with given IDs from the Supervisely server.
`remove_items`	Remove items from Entities Collection.
`update`

Attributes

`MAX_WAIT_ATTEMPTS`	Maximum number of attempts that will be made to wait for a certain condition to be met.
`WAIT_ATTEMPT_TIMEOUT_SEC`	Number of seconds for intervals between attempts.

InfoType¶: alias of supervisely.api.module_api.EntitiesCollectionInfo

add_items(id, items)[source]¶

Add items to Entities Collection.

Parameters

id : int: Entities Collection ID in Supervisely.
items : List[Union[int, CollectionItem]]: List of items to add to the collection. Could be a list of entity IDs (int) or CollectionItem objects.

Returns

List of added items with their IDs and creation timestamps.

Return type

List[Dict[str, int]]

Usage example

import supervisely as sly
from supervisely.api.entities_collection_api import CollectionItem

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

collection_id = 2
item_ids = [525, 526]
items = [CollectionItem(entity_id=item_id) for item_id in item_ids]
new_items = api.entities_collection.add_items(collection_id, items)
print(new_items)
# Output: [
#   {"id": 1, "entityId": 525, 'createdAt': '2025-04-10T08:49:41.852Z'},
#   {"id": 2, "entityId": 526, 'createdAt': '2025-04-10T08:49:41.852Z'}
]

classmethod convert_info_to_json(info)¶

_convert_info_to_json

Return type: Dict

create(project_id, name, description=None, type='default', ai_search_key=None)[source]¶

Creates Entities Collections.

Parameters

project_id : int: Project ID in Supervisely.
name : str: Entities Collection name in Supervisely.
description : str: Entities Collection description.
type : str: Type of the collection. Defaults to “default”.
ai_search_key : Optional[str]: AI search key for the collection. Defaults to None.

Returns

Information about new Entities Collection

Return type

EntitiesCollectionInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

project_id = 123
name = "Chihuahuas"
description = "Collection of Chihuahuas"
type = CollectionType.AI_SEARCH
ai_search_key = "0ed6a5256433bbe32822949d563d476a"

new_collection = api.entities_collection.create(project_id, name, description, type, ai_search_key)
print(new_collection)

exists(parent_id, name)¶

Checks if an entity with the given parent_id and name exists

Parameters

parent_id : int: ID of the parent entity.
name : str: Name of the entity.

Returns

Returns True if entity exists, and False if not

Return type

bool

Usage example

import supervisely as sly

# You can connect to API directly
address = 'https://app.supervisely.com/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True

get_free_name(parent_id, name)¶

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters

parent_id : int: ID of the parent entity.
name : str: Name of the entity.

Returns

Returns free name.

Return type

str

Usage example

import supervisely as sly

# You can connect to API directly
address = 'https://app.supervisely.com/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg

get_info_by_ai_search_key(project_id, ai_search_key)[source]¶

Get information about Entities Collection of type CollectionType.AI_SEARCH with given AI search key.

Parameters

project_id : int: Project ID in Supervisely.
ai_search_key : str: AI search key for the collection.

Returns

Information about Entities Collection.

Return type

EntitiesCollectionInfo

Usage example

get_info_by_id(id, with_meta=False)[source]¶

Get information about Entities Collection with given ID.

Parameters

id : int: Entities Collection ID in Supervisely.
with_meta : bool, optional: If True, includes meta information in the response. Defaults to False.

Returns

Information about Entities Collection.

Return type

EntitiesCollectionInfo

Usage example

import supervisely as sly

os.environ[‘SERVER_ADDRESS’] = ‘https://app.supervisely.com’ os.environ[‘API_TOKEN’] = ‘Your Supervisely API Token’ api = sly.Api.from_env()

collection = api.entities_collection.get_info_by_id(2) print(collection) # Output: # { # “id”: 1, # “teamId”: 1, # “projectId”: 1, # “name”: “ds”, # “description”: “”, # “createdAt”: “2018-08-21T14:25:56.140Z”, # “updatedAt”: “2018-08-21T14:25:56.140Z” # }

get_info_by_name(parent_id, name, fields=[])¶

Get information about an entity by its name from the Supervisely server.

Parameters

parent_id : int: ID of the parent entity.
name : str: Name of the entity for which the information is being retrieved.
fields : List[str]: The list of api fields which will be returned with the response.

Usage example

import supervisely as sly

# You can connect to API directly
address = 'https://app.supervisely.com/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


dataset_id = 55832
name = "IMG_0315.jpeg"
info = api.image.get_info_by_name(dataset_id, name)
print(info)
# Output: ImageInfo(id=19369643, name='IMG_0315.jpeg', ...)

get_items(collection_id, collection_type, project_id=None, ai_search_threshold=None, ai_search_threshold_direction='above')[source]¶

Get items from Entities Collection.

Parameters

collection_id : int: Entities Collection ID in Supervisely.
collection_type : CollectionTypeFilter: Type of the collection. Can be CollectionTypeFilter.AI_SEARCH or CollectionTypeFilter.DEFAULT.
project_id : int, optional: Project ID in Supervisely.
ai_search_threshold : float, optional: AI search threshold for filtering items. Optional, defaults to None.
ai_search_threshold_direction : str: Direction for the AI search threshold. Optional, defaults to ‘above’.

Returns

List of ImageInfo objects.

Return type

List[ImageInfo]

Raises

RuntimeError – If Entities Collection with given ID not found.

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

collection_id = 2
project_id = 4
item_ids = api.entities_collection.get_items(collection_id, project_id)
print(item_ids)

get_list(project_id, filters=None, with_meta=False, collection_type='default')[source]¶

Get list of information about Entities Collection for the given project.

Parameters

project_id : int, optional

Project ID in Supervisely.

filters : List[Dict[str, str]], optional

List of filters to apply to the request. Optional, defaults to None.

with_meta : bool, optional

If True, includes meta information in the response. Defaults to False.

collection_type : CollectionType

Type of the collection. Defaults to CollectionType.DEFAULT.

Available types are:

CollectionType.DEFAULT
CollectionType.AI_SEARCH
CollectionType.ALL

Returns

List of information about Entities Collections.

Return type

List[EntitiesCollectionInfo]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

collections = api.entities_collection.get_list(4)

get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

Get list of all or limited quantity entities from the Supervisely server.

Parameters

method : str: Request method name
data : dict: Dictionary with request body info
progress_cb : Progress, optional: Function for tracking download progress.
convert_json_info_cb : Callable, optional: Function for convert json info
limit : int, optional: Number of entity to retrieve
return_first_response : bool, optional: Specify if return first response

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters

method : str: Request method name
data : dict: Dictionary with request body info
progress_cb : Progress, optional: Function for tracking download progress.
convert_json_info_cb : Callable, optional: Function for convert json info
limit : int, optional: Number of entity to retrieve
return_first_response : bool, optional: Specify if return first response

async get_list_idx_page_async(method, data)¶

Get the list of items for a given page number. Page number is specified in the data dictionary.

Parameters

method : str: Method to call for listing items.
data : dict: Data to pass to the API method.

Returns

List of items.

Return type

Tuple[int, List[NamedTuple]]

async get_list_page_generator_async(method, data, pages_count=None, semaphore=None)¶

Yields list of images in dataset asynchronously page by page.

Parameters

method : str: Method to call for listing items.
data : dict: Data to pass to the API method.
pages_count : int, optional: Preferred number of pages to retrieve if used with a per_page limit. Will be automatically adjusted if the pagesCount differs from the requested number.
semaphore : asyncio.Semaphore, optional: Semaphore for limiting the number of simultaneous requests.
kwargs: Additional arguments.

Returns

List of images in dataset.

Return type

AsyncGenerator[List[ImageInfo]]

Usage example

import supervisely as sly
import asyncio

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

method = 'images.list'
data = {
    'datasetId': 123456
}

loop = sly.utils.get_or_create_event_loop()
images = loop.run_until_complete(api.image.get_list_generator_async(method, data))

static info_sequence()[source]¶

NamedTuple EntitiesCollectionInfo information about Entities Collection.

Example

 EntitiesCollectionInfo(
    id=2,
    name='Enitites Collections #1',
    team_id=4,
    project_id=58,
    description='',
    created_at='2020-04-08T15:10:12.618Z',
    updated_at='2020-04-08T15:10:19.833Z',
)

static info_tuple_name()[source]¶

Get string name of EntitiesCollectionInfo NamedTuple.

Returns: NamedTuple name.
Return type: str

remove(id, force=False)[source]¶

Remove Entites Collection with the specified ID from the Supervisely server.

If force is set to True, the collection will be removed permanently. If force is set to False, the collection will be disabled instead of removed.

Parameters

id : int: Entites Collection ID in Supervisely
force : bool: If True, the collection will be removed permanently. Defaults to False.

Returns

None

remove_batch(ids, progress_cb=None)¶

Remove entities with given IDs from the Supervisely server.

Parameters

ids : List[int]: IDs of entities in Supervisely.
progress_cb : Callable: Function for control remove progress.

remove_items(id, items)[source]¶

Remove items from Entities Collection.

Parameters

id : int: Entities Collection ID in Supervisely.
items : List[int]: List of entity IDs in Supervisely, e.g. image IDs etc.

Usage example

import supervisely as sly
api = sly.Api.from_env()

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

Return type

List[Dict[str, int]]

update(id, name=None, description=None)¶