Items#
- SAClient.query(project, query=None, subset=None)#
Return items that satisfy the given query. Query syntax should be in SuperAnnotate query language(https://doc.superannotate.com/docs/explore-overview).
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”)
query (str) – SAQuL query string.
subset (str) – subset name. Allows you to query items in a specific subset. To return all the items in the specified subset, set the value of query param to None.
- Returns:
queried items’ metadata list
- Return type:
list of dicts
- SAClient.get_item_by_id(project_id, item_id)#
Returns the item metadata
- Parameters:
project_id (int) – the id of the project
item_id (int) – the id of the item
- Returns:
item metadata
- Return type:
dict
- SAClient.list_items(project, folder=None, *, include=None, **filters)#
Search items by filtering criteria.
- Parameters:
project (Union[int, str]) – The project name, project ID, or folder path (e.g., “project1/folder1”) to search within. This can refer to the root of the project or a specific subfolder.
folder (Union[int, str], optional) – The folder name or ID to search within. If None, the search will be done in the root folder of the project. If both “project” and “folder” specify folders, the “project” value will take priority.
include (list of str, optional) –
Specifies additional fields to include in the response.
Possible values are
”custom_metadata”: Includes custom metadata attached to the item.
filters (ItemFilters) –
- Specifies filtering criteria (e.g., name, ID, annotation status),
with all conditions combined using logical AND. Only items matching all criteria are returned. If no operation is specified, an exact match is applied.
- Supported operations:
__ne: Value is in the list.
__in: Value is not equal.
__notin: Value is not in the list.
__contains: Value has the substring.
__starts: Value starts with the prefix.
__ends: Value ends with the suffix.
Filter params:
- id: int - id__in: list[int] - name: str - name__in: list[str] - name__contains: str - name__starts: str - name__ends: str - approval_status: Literal["Approved", "Disapproved", None] - assignments__user_id: str - assignments__user_id__ne: str - assignments__user_id__in: list[str] - assignments__user_role: str - assignments__user_id__ne: str - assignments__user_role__in: list[str] - assignments__user_role__notin: list[str]
- Returns:
A list of items that match the filtering criteria.
- Return type:
list of dicts
Request Example:
client.list_items( project="Medical Annotations", folder="folder1", include=["custom_metadata"], annotation_status="InProgress", name_contains="scan" )
Response Example:
[ { "name": "scan_123.jpeg", "path": "Medical Annotations/folder1", "url": "https://sa-public-files.s3.../scan_123.jpeg", "annotation_status": "InProgress", "createdAt": "2022-02-10T14:32:21.000Z", "updatedAt": "2022-02-15T20:46:44.000Z", "custom_metadata": { "study_date": "2021-12-31", "patient_id": "62078f8a756ddb2ca9fc9660", "medical_specialist": "robertboxer@ms.com" } } ]
Additional Filter Examples:
client.list_items( project="Medical Annotations", folder="folder2", annotation_status="Completed", name__in=["1.jpg", "2.jpg", "3.jpg"] ) # Filter items assigned to a specific QA client.list_items( project="Medical Annotations", assignee__user_id="qa@example.com" )
- SAClient.search_items(project, name_contains=None, annotation_status=None, annotator_email=None, qa_email=None, recursive=False, include_custom_metadata=False)#
Search items by filtering criteria.
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”). If recursive=False=True, then only the project name is required.
name_contains (str) – Returns those items, where the given string is found anywhere within an item’s name. If None, all items returned, in accordance with the recursive=False parameter.
annotation_status (str) –
if not None, filters items by annotation status.
Available statuses are:
* NotStarted * InProgress * QualityCheck * Returned * Completed * Skipped
annotator_email (str) – returns those items’ names that are assigned to the specified annotator. If None, all items are returned. Strict equal.
qa_email (str) – returns those items’ names that are assigned to the specified QA. If None, all items are returned. Strict equal.
recursive (bool) – search in the project’s root and all of its folders. If False search only in the project’s root or given directory.
include_custom_metadata (bool) – include custom metadata that has been attached to an asset.
- Returns:
metadata of item
- Return type:
list of dicts
Request Example:
client.search_items( project="Medical Annotations", name_contains="image_1", include_custom_metadata=True )
Response Example:
[ { "name": "image_1.jpeg", "path": "Medical Annotations/Study", "url": "https://sa-public-files.s3.../image_1.png", "annotation_status": "NotStarted", "annotator_email": None, "qa_email": None, "entropy_value": None, "createdAt": "2022-02-15T20:46:44.000Z", "updatedAt": "2022-02-15T20:46:44.000Z", "custom_metadata": { "study_date": "2021-12-31", "patient_id": "62078f8a756ddb2ca9fc9660", "patient_sex": "female", "medical_specialist": "robertboxer@ms.com", } } ]
- SAClient.attach_items(project, attachments, annotation_status=None)#
Link items from external storage to SuperAnnotate using URLs.
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”)
attachments (path-like (str or Path) or list of dicts) – path to CSV file or list of dicts containing attachments URLs.
annotation_status (str) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.
- Returns:
uploaded, failed and duplicated item names
- Return type:
tuple of list of strs
Example:
client = SAClient() client.attach_items( project="Medical Annotations", attachments=[{"name": "item", "url": "https://..."}] )
Example of attaching items from custom integration:
client = SAClient() client.attach_items( project="Medical Annotations", attachments=[ { "name": "item", "url": "https://bucket-name.s3…/example.png" "integration": "custom-integration-name" } ] )
- SAClient.copy_items(source, destination, items=None, include_annotations=True)#
Copy images in bulk between folders in a project
- Parameters:
source (str) – project name or folder path to select items from (e.g., “project1/folder1”).
destination (str) – project name (root) or folder path to place copied items.
items (list of str) – names of items to copy. If None, all items from the source directory will be copied.
include_annotations (bool) – enables annotations copy
- Returns:
list of skipped item names
- Return type:
list of strs
- SAClient.move_items(source, destination, items=None)#
Move images in bulk between folders in a project
- Parameters:
source (str) – project name or folder path to pick items from (e.g., “project1/folder1”).
destination (str) – project name (root) or folder path to move items to.
items (list of str) – names of items to move. If None, all items from the source directory will be moved.
- Returns:
list of skipped item names
- Return type:
list of strs
- SAClient.delete_items(project, items=None)#
Delete items in a given project.
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”)
items (list of str) – to be deleted items’ names. If None, all the items will be deleted
- SAClient.assign_items(project, items, user)#
Assigns items to a user. The assignment role, QA or Annotator, will be deduced from the user’s role in the project. The type of the objects` image, video or text will be deduced from the project type. With SDK, the user can be assigned to a role in the project with the share_project function.
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”)
items (list of str) – list of items to assign
user (str) – user email
- SAClient.unassign_items(project, items)#
Removes assignment of given items for all assignees. With SDK, the user can be assigned to a role in the project with the share_project function.
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”)
items (list of str) – list of items to unassign
- SAClient.get_item_metadata(project, item_name, include_custom_metadata=False)#
Returns item metadata
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”)
item_name (str) – item name.
include_custom_metadata (bool) – include custom metadata that has been attached to an asset.
- Returns:
metadata of item
- Return type:
dict
Request Example:
client.get_item_metadata( project="Medical Annotations", item_name = "image_1.png", include_custom_metadata=True )
Response Example:
{ "name": "image_1.jpeg", "path": "Medical Annotations/Study", "url": "https://sa-public-files.s3.../image_1.png", "annotation_status": "NotStarted", "annotator_email": None, "qa_email": None, "entropy_value": None, "createdAt": "2022-02-15T20:46:44.000Z", "updatedAt": "2022-02-15T20:46:44.000Z", "custom_metadata": { "study_date": "2021-12-31", "patient_id": "62078f8a756ddb2ca9fc9660", "patient_sex": "female", "medical_specialist": "robertboxer@ms.com", } }
- SAClient.set_approval_statuses(project, approval_status, items=None)#
Sets annotation statuses of items
- Parameters:
project (str) – project name or folder path (e.g., “project1/folder1”).
approval_status (str) –
approval status to set.
Available statuses are:
* None * Approved * Disapproved
items (list of strs) – item names to set the mentioned status for. If None, all the items in the project will be used.