Explore#

SAClient.explore groups the functions that operate on the Explore surface of the platform. Every query in this namespace uses the SuperAnnotate query language documented at https://doc.superannotate.com/docs/queries-beta.

Explore.query(project, query=None, subset=None)#

Return items that satisfy the given Explore query. Query syntax should be in the SuperAnnotate query language (https://doc.superannotate.com/docs/queries-beta).

The returned QueryResult behaves like a list of dicts, and additionally exposes a .count() method.

Parameters:
  • project (Union[str, int, Tuple[int, int], Tuple[str, str]]) – Accepts a project as a string (“project” or “project/folder”) or as a tuple (project_id, folder_id), where the folder is optional.

  • query (str) – Explore query string.

  • subset (str) – Subset name. Restricts the query to items in the given subset. To return all the items in the specified subset, leave the query as None.

Returns:

queried items’ metadata list

Return type:

QueryResult (list of dicts with .count() method)

Raises:

AppException – If both query and subset are left empty, if the project, folder or subset is not found, or with the backend’s message if the query is rejected (e.g. an invalid query string, or a project that was never resynced).

Request Example:

# To query by status:
sa_client.explore.query(
    project="Image Project",
    query='_status = "InProgress"'
)

# To query within a subset:
sa_client.explore.query(
    project="Image Project",
    query='_status = "InProgress"',
    subset="golden-set"
)

Response Example:

[
    {
        "id": 196560932,
        "name": "TEST_00001",
        "folder_id": 867191,
        "comments": [],
        "annotation_status": "InProgress",
        "path": "custom_llm",
        "approval_status": 0,
        "createdAt": "2026-08-04T03:50:53.000Z",
        "updatedAt": "2026-09-02T10:37:18.000Z",
        "meta": {"integration_id": None},
        "instances": [],
        "custom_metadata": {},
        "subset_ids": [],
        "category_id": [],
        "category_name": None,
        "assignment": [],
        "last_action": {
            "date": "2026-09-02T10:37:17.217Z",
            "email": "test@superannotate.com"
        },
        "score": [],
        "is_pinned": 0,
        "folder_name": "root",
        "is_root_folder": 1
    }
]
query.count() → int#

Returns the total number of items matching the query, without fetching item metadata.

Returns:

total number of matching items

Return type:

int

Request Example:

total = sa_client.explore.query(
    project="Image Project", query='_status = "InProgress"'
).count()
print(f"Total matching items: {total}")
Explore.get_subsets(project)#

Returns the subsets that exist in the given project.

Parameters:

project (Union[str, int]) – The name or ID of the project.

Returns:

subsets’ metadata

Return type:

list of dicts

Request Example:

subsets = sa_client.explore.get_subsets(project="Image Project")

Response Example:

[{'name': 'test_subset'}]
Explore.add_items_to_subset(project, subset, items)#

Associates selected items with a given subset. Non-existing subset will be automatically created.

Parameters:
  • project (Union[str, int]) – The name or ID of the project.

  • subset (str) – a name of an existing/new subset to associate items with. New subsets will be automatically created.

  • items (list of dicts) – list of items metadata. Required keys are ‘name’ and ‘path’ if the ‘id’ key is not provided in the dict.

Returns:

dictionary with succeeded, skipped, and failed items lists.

Return type:

dict

Request Example:

sa_client = SAClient()

# option 1
queried_items = sa_client.explore.query(
    project="Image Project",
    query='_status = "InProgress"'
)

sa_client.explore.add_items_to_subset(
    project="Medical Annotations",
    subset="Brain Study - Disapproved",
    items=queried_items
)

# option 2
items_list = [
    {
        'name': 'image_1.jpeg',
        'path': 'Image Project'
    },
    {
        'name': 'image_2.jpeg',
        'path': 'Image Project/Subfolder A'
    }
]

sa_client.explore.add_items_to_subset(
    project="Image Project",
    subset="Subset Name",
    items=items_list
)

Response Example:

{
    "succeeded": [
        {
            'name': 'image_1.jpeg',
            'path': 'Image Project'
        },
        {
            'name': 'image_2.jpeg',
            'path': 'Image Project/Subfolder A'
        }
    ],
    "failed": [],
    "skipped": []
}