Items

Attach items

You can attach items via a list of URLs or via URLs in a CSV file.

To attach items via a list of URLs:

sa.attach_items(
    project = "Cars",
    attachments = [
        { "name": "16797.jpg", 
          "url": "https://test-1212.s3.amazonaws.com/50k2sep/0.jpg?AWSAccessKeyId=AKIA5BP2G2NHEPGBCUX2&Signature=oNlHqhZHiK5GzgWZi%2F46dIoQ%2B%2BA%3D&Expires=1651063405" },
        { "name": "16798.jpg", 
          "url": "https://test-1212.s3.amazonaws.com/50k2sep/1.jpg?AWSAccessKeyId=AKIA5BP2G2NHEPGBCUX2&Signature=bYWiGrW8ET56pUcTCrlqhF5EX%2BY%3D&Expires=1651063405" },
        { "name": "16799.jpg", 
          "url": "https://test-1212.s3.amazonaws.com/50k2sep/10.jpg?AWSAccessKeyId=AKIA5BP2G2NHEPGBCUX2&Signature=OXtzqrgAlEViDbTM5RHeOA%2BGBLk%3D&Expires=1651063405" }
    ],
    annotation_status="NotStarted"
)

To attach items via CSV files:

sa.attach_items(
    project = "Trucks",
    attachments = "/Users/joshbrown/trucks_image_urls.csv", 
    annotation_status="NotStarted"
)

Move items

To move items in bulk from one folder to another:

sa.move_items(
    source = "Project 1/Folder 1", 
    destination = "Project 1/Folder 2", 
    items = ["analysis1.txt","analysis2.txt"], 
)

Copy items

To copy items from one folder and paste them in another folder:

sa.copy_items(
    source = "Project 1/Folder 1", 
    destination = "Project 1/Folder 2", 
    items = ["947483.jpeg","847484.jpeg"], 
    include_annotations = False
)

Set annotation status

To set the annotation status of one item or multiple items:

SAClient.set_annotation_statuses(
    project = "Sentiment Analysis",
    annotation_status = "QualityCheck",
    items = ["56038.txt", "56039.txt"]
)

Set approval status

To change the approval status of items in bulk:

SAClient.set_approval_statuses(
	project="Project Name",
	approval_status="Approved",
	items=["947483.jpeg","847484.jpeg"]
)

Query

To run a query:

SAClient.query(
	project = "Project 1",
	query = "metadata(status = InProgress AND annotatorEmail = [email protected])" 
)

This function returns the metadata of the items in a list form.

To get all the items from a subset:

SAClient.query(
  project="Image Project",
  query=None,
  subset="Subset 1"
)

The output will be the metadata of the subset's items. Here's an example:

[{'createdAt': '2022-04-03T13:38:58.000Z', 'updatedAt': '2022-04-28T15:14:01.000Z',
 'name': 'Image 1.jpeg',
 'path': 'Project 1/Subfolder 1',
 'url': None,
 'annotator_email': '[email protected]',
 'qa_email': None,
 'annotation_status': 'InProgress',
 'entropy_value': 8140.11,
 'approval_status': 'disapproved',
 'is_pinned': False},
{'createdAt': '2022-04-03T13:38:59.000Z',
 'updatedAt': '2022-05-06T14:53:24.000Z',
 'name': 'Image 2.jpeg',
 'path': 'Project 1/Subfolder 1',
 'url': None,
 'annotator_email': '[email protected]',
 'qa_email': None,
 'annotation_status': 'Completed',
 'entropy_value': 8691.52,
 'approval_status': None,
 'is_pinned': False}]

To run a query in a subset:

SAClient.query(
  project="Image Project",
  query="metadata(annotatorEmail = [email protected])", 
  subset="Subset 1"
)

The output is the metadata of the query's items. Here's an example:

[{'createdAt': '2022-04-03T13:38:58.000Z', 'updatedAt': '2022-04-28T15:14:01.000Z',
 'name': 'Image 1.jpeg',
 'path': 'Project 1/Subfolder 1',
 'url': None,
 'annotator_email': '[email protected]',
 'qa_email': None,
 'annotation_status': 'InProgress',
 'entropy_value': 8140.11,
 'approval_status': 'disapproved',
 'is_pinned': False}]

Learn more about queries here.

Search items

To search for items in a project:

superannotate.search_items(
  project="Project 1")

To search for items whose names contain car:

superannotate.search_items(
  project="Project 1", 
  name_contains="car")

To search for items whose names contain car and have the annotation status InProgress:

superannotate.search_items(
  project="Project 1", 
  name_contains="car",
  annotation_status="InProgress")

To search for items by the assigned Annotator and QA’s email addresses:

superannotate.search_items(
  project="Project 1", 
  name_contains="car",
  annotation_status="InProgress",
  annotator_email="[email protected]",
  qa_email="[email protected]")

📘
Annotation status
The annotation_status field can have one of the following values: NotStarted, InProgress, QualityCheck, Returned, Completed, and Skipped.

To search for items in the whole project, including folders:

superannotate.search_items(
  project="Project 1", 
  name_contains="car",
  annotation_status="InProgress",
  annotator_email="[email protected]",
  qa_email="[email protected]",      
  recursive=True
)

📘
The function will return a list of metadata objects for items that satisfy search criteria.

To search for items whose name contains image_1 with their custom metadata:

SAClient.search_items(
   project="Medical Annotations",
   name_contains="image_1",
   include_custom_metadata=True
)

The output will be:

[
   {
       "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": "[email protected]",
       }
   }
]

If include_custom_metadata is set to False, then the output will be the following:

[
   {
       "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"
   }
]

Assign and unsassign items

To assign items to a user:

assignments = [item['name'] for item in sa.search_items("Project 1")] print(assignments)

sa.assign_items(
   project = "Project 1", 
   items = assignments,
   user = '[email protected]' 
)

To unassign an item from a user:

assignments = [item['name'] for item in sa.search_items("Project 1")] print(assignments)

sa.unassign_items(
   project = "Project 1", 
   items = assignments,
)

Delete items

To delete items:

sa.delete_items(
   project="Project 1", 
   items=['img_1.png', 'img_2.png']
)

Get item metadata

To get an item’s metadata:

superannotate.get_item_metadata(
	project="Project 1",
	item_name="Image1.png")

Here’s the returned data.

Image

{
   "name": "example.jpeg",
   "path": "project/folder_1",    
   "url": "https://sa-public-files.s3.../text_file_example_1.jpeg",
   "annotation_status": "NotStarted",
   "annotator_email": "[email protected]",
   "qa_email": "[email protected]",
   "entropy_value": null,
   "createdAt": "2022-02-15T20:46:44.000Z", 
   "updatedAt": "2022-02-15T20:46:44.000Z",
   "approval_status": "disapproved",
   "is_pinned" : False
}

Description:

name: File name
path: Item’s path in the SuperAnnotate project. This is an example of a path: <project>/<folder>/<itemname>.
url: Item’s URL. If the item was uploaded from the computer, the value is None. If the item was added via an integration, the value is the integration storage’s path. If the item is attached, the value is the URL.
annotation_status: The item’s annotation status.
annotator_email: The assigned annotator’s email address.
qa_email: The assigned QA’s email address.
entropy_value: The item’s priority score.
createdAt: The date when the item was created.
updatedAt: The date when the item was last updated.
approval_status: The item’s approval status. The values are approved for approved items and disapproved for disapproved items. It’s None for items that are neither approved nor disapproved.
is_pinned: The value is True for pinned items and False for items that aren't pinned.

Video

{
   "name": "example.jpeg",
   "path": "project/folder_1/meow.jpeg",
   "url": "https://sa-public-files.s3.../text_file_example_1.jpeg",
   "annotation_status": "NotStarted",
   "annotator_email": null,
   "qa_email": null,
   "entropy_value": null,
   "createdAt": "2022-02-15T20:46:44.000Z", 
   "updatedAt": "2022-02-15T20:46:44.000Z",
   "approval_status": "approved"
}

Description:

name: File name
path: Item’s path in the SuperAnnotate project.
url: Item’s URL. If the item was added via an integration, the value is the integration storage’s path. If the item is attached, the value is the URL.
annotation_status: The item’s annotation status.
annotator_email: The assigned annotator’s email address.
qa_email: The assigned QA’s email address.
entropy_value: The item’s priority score.
createdAt: The date when the item was created.
updatedAt: The date when the item was last updated.
approval_status: The item’s approval status. The values are approved for approved items and disapproved for disapproved items. It’s None for items that are neither approved nor disapproved.

Document

{
   "name": "example.jpeg",
   "path": "project/folder_1/meow.jpeg", // <proj>/<folder>/<itemname>
   "url": "https://sa-public-files.s3.../text_file_example_1.jpeg",
   "annotation_status": "NotStarted",
   "annotator_name": null,
   "qa_name": null,
   "entropy_value": null,
   "createdAt": "2022-02-15T20:46:44.000Z", 
   "updatedAt": "2022-02-15T20:46:44.000Z" 
}

Description:

name: File name
path: Item’s path in the SuperAnnotate project.
url: Item’s URL. . If the item was added via an integration, the value is the integration storage’s path. If the item is attached, the value is the URL.
annotation_status: The item’s annotation status.
annotator_email: The assigned annotator’s email address.
qa_email: The assigned QA’s email address.
entropy_value: The item’s priority score.
createdAt: The date when the item was created.
updatedAt: The date when the item was last updated.