Team#

SAClient.get_team_metadata(include=None)#

Returns team metadata, including optionally, scores.

Parameters:

include (list of str, optional) –

Specifies additional fields to include in the response.

Possible values are

”scores”: If provided, the response will include score names associated with the team user.

Returns:

team metadata

Return type:

dict

SAClient.list_workflows()#

Lists team’s all workflows and their metadata

Returns:: metadata of workflows
Return type:: list of dicts

Request Example:

sa_client.list_workflows()

Response Example:

[
    {
        "createdAt": "2024-09-03T12:48:09.000Z",
        "updatedAt": "2024-09-04T12:48:09.000Z",
        "id": 1,
        "name": "System workflow",
        "type": "system",
        "description": "This workflow is generated by the system, and prevents annotators from completing items."
    },
    {
        "createdAt": "2025-01-03T12:48:09.000Z",
        "updatedAt": "2025-01-05T12:48:09.000Z",
        "id": 58758,
        "name": "Custom workflow",
        "type": "user",
        "description": "This workflow custom build."
    }
]

SAClient.get_integrations()#

Get all integrations per team

Returns:: metadata objects of all integrations of the team.
Return type:: list of dicts

Request Example:

sa_client.get_integrations()

Response Example:

[
    {
        "createdAt": "2023-11-27T11:16:02.000Z",
        "id": 5072,
        "name": "My S3 Bucket",
        "root": "test-openseadragon-1212",
        "type": "aws",
        "updatedAt": "2023-12-27T11:16:02.000Z",
        "creator_id": "example@superannotate.com"
    }
]

SAClient.invite_contributors_to_team(emails, admin=False)#

Invites contributors to the team.

Parameters:

emails (list) – list of contributor emails
admin (bool) – enables admin privileges for the contributor

Returns:

lists of invited, skipped contributors of the team

Return type:

tuple (2 members) of lists of strs

SAClient.get_user_metadata(pk, include=None)#

Returns user metadata including optionally, custom fields

Parameters:

pk (str or int) – The email address or ID of the team user.
include (list of str, optional) –
Specifies additional fields to include in the response.

Possible values are
- ”custom_fields”: If provided, the response will include custom fields associated with the team user.

Returns:

metadata of team user.

Return type:

dict

Request Example:

sa_client.get_user_metadata(
    "example@email.com",
    include=["custom_fields"]
)

Response Example:

{
    "createdAt": "2023-11-27T07:10:24.000Z",
    "updatedAt": "2025-02-03T13:35:09.000Z",
    "custom_fields": {
        "ann_quality_threshold": 80,
        "tag": ["Tag1", "Tag2", "Tag3"],
        "due_date": 1738671238.7,
    },
    "email": "example@email.com",
    "id": 124341,
    "role": "Contributor",
    "state": "Confirmed",
    "team_id": 23245,
}

SAClient.set_user_custom_field(pk, custom_field_name, value)#

Set the custom field for team user.

Parameters:

pk (str or int) – The email address or ID of the team user.
custom_field_name (str) – The name of the existing custom field assigned to the user.
value (Any) –
The new value for the custom field.
- This can be a string, a list of strings, a number, or None depending on the custom field type.
- Multi-select fields must be provided as a list of strings (e.g., [“Tag1”, “Tag2”]).
- Date fields must be in Unix timestamp format (e.g., “1738281600”).
- Other fields (e.g., text, numbers) should match the expected type as defined in the project schema.

Request Example:

sa_client.set_user_custom_field(
    "example@email.com",
    custom_field_name="due_date",
    value=1738671238.7
)

SAClient.list_users(*, project=None, include=None, **filters)#

Search users, including their scores, by filtering criteria.

Parameters:

project (str or int) – Project name or ID, if provided, results will be for project-level, otherwise results will be for team level.
include (list of str, optional) –
Specifies additional fields to be included in the response.

Possible values are
- ”custom_fields”: Includes custom fields and scores assigned to each user.
- ”categories”: Includes a list of categories assigned to each project contributor. Note: ‘project’ parameter must be specified when including ‘categories’.
filters (UserFilters, optional) –
Specifies filtering criteria, with all conditions combined using logical AND.
- Only users matching all filter conditions are returned.
- If no filter operation is provided, an exact match is applied
Supported operations:
- __in: Value is in the provided list.
- __notin: Value is not in the provided list.
- __ne: Value is not equal to the given value.
- __contains: Value contains the specified substring.
- __starts: Value starts with the given prefix.
- __ends: Value ends with the given suffix.
- __gt: Value is greater than the given number.
- __gte: Value is greater than or equal to the given number.
- __lt: Value is less than the given number.
- __lte: Value is less than or equal to the given number.
Filter params:
```
- id: int
- id__in: list[int]
- email: str
- email__in:  list[str]
- email__contains: str
- email__starts: str
- email__ends: str
```
Following params if project is selected:
```
- role: str
- role__in: List[str]
```
Following params if project is not selected:
```
- state: Literal[“Confirmed”, “Pending”]
- state__in: List[Literal[“Confirmed”, “Pending”]]
- role: Literal[“admin”, “contributor”]
- role__in: List[Literal[“admin”, “contributor”]]
```
Scores and Custom Field Filtering:
- Scores and other custom fields must be prefixed with custom_field__ .
- Example: custom_field__Due_date__gte=”1738281600” (filtering users whose Due_date is after the given Unix timestamp).
- Text custom field only works with the following filter params: __in, __notin, __contains
- Numeric custom field only works with the following filter params: __in, __notin, __ne, __gt, __gte, __lt, __lte
- Single-select custom field only works with the following filter params: __in, __notin, __contains
- Multi-select custom field only works with the following filter params: __in, __notin
- Date picker custom field only works with the following filter params: __gt, __gte, __lt, __lte
If custom field has a space, please use the following format to filter them:
```
user_filters = {"custom_field__accuracy score 30D__lt": 90}
sa_client.list_users(include=["custom_fields"], **user_filters)
```

Returns:

A list of team/project users metadata that matches the filtering criteria

Return type:

list of dicts

Request Example:

sa_client.list_users(
    email__contains="@superannotate.com",
    include=["custom_fields"],
    state__in=["Confirmed"]
    custom_fields__Tag__in=["Tag1", "Tag3"]
)

Response Example:

[
    {
        "createdAt": "2023-02-02T14:25:42.000Z",
        "updatedAt": "2025-01-23T16:39:03.000Z",
        "custom_fields": {
            "Ann Quality threshold": 80,
            "Tag": ["Tag1", "Tag2", "Tag3"],
        },
        "email": "example@superannotate.com",
        "id": 30328,
        "role": "TeamOwner",
        "state": "Confirmed",
        "team_id": 44311,
        "user_permissions": [],
    }
]

Request Example:

# Project level scores

scores = sa_client.list_users(
    include=["custom_fields"],
    project="my_multimodal",
    email__contains="@superannotate.com",
    custom_field__speed__gte=90,
    custom_field__weight__lte=1
)

Response Example:

# Project level scores

[
    {
        "createdAt": "2025-03-07T13:19:59.000Z",
        "updatedAt": "2025-03-07T13:19:59.000Z",
        "custom_fields": {"speed": 92, "weight": 0.8},
        "email": "example@superannotate.com",
        "id": 715121,
        'permissions': {
            'allow_orchestrate': 0,
            'allow_run_explore': 0,
            'allow_view_sdk_token': 0,
            'paused': 0
        },
        "role": "Annotator",
        "state": "Confirmed",
        "team_id": 1234,
        "categories": None,
        "user_permissions": [],
    }
]

Request Example:

# Team level scores

user_filters = {
    "custom_field__accuracy score 30D__lt": 95,
    "custom_field__speed score 7D__lt": 15
}

scores = sa_client.list_users(
    include=["custom_fields"],
    email__contains="@superannotate.com",
    role="Contributor",
    **user_filters
)

Response Example:

# Team level scores

[
    {
        "createdAt": "2025-03-07T13:19:59.000Z",
        "updatedAt": "2025-03-07T13:19:59.000Z",
        "custom_fields": {
            "Test custom field": 80,
            "Tag custom fields": ["Tag1", "Tag2"],
            "accuracy score 30D": 95,
            "accuracy score 14D": 47,
            "accuracy score 7D": 24,
            "speed score 30D": 33,
            "speed score 14D": 22,
            "speed score 7D": 11,
        },
        "email": "example@superannotate.com",
        "id": 715121,
        "role": "Contributor",
        "state": "Confirmed",
        "team_id": 1234,
        "user_permissions": [],
    }
]

User Permissions

Every returned user includes a user_permissions list.

The contents depend on whether the project parameter is provided:

If project is specified, user_permissions contains the permissions granted to the user within that project (e.g. Download).
If project is omitted, user_permissions contains the team-level permissions granted to the user (e.g. Remove Contributors from team).

Request Example:

project_user = sa_client.list_users(
    project="my_multimodal",
    email="test@superannotate.com",
)

Response Example:

[
    {
      'createdAt': '2026-05-19T08:28:55.000Z',
      'custom_fields': {},
      'email': 'test@superannotate.com',
      'id': 1622408,
      'permissions': {
        'allow_orchestrate': 0,
        'allow_run_explore': 0,
        'allow_view_sdk_token': 0,
        'paused': 0
      },
      'role': 'ProjectAdmin',
      'state': 'Confirmed',
      'team_id': 32022,
      'updatedAt': '2026-05-19T08:28:55.000Z',
      'categories': None,
      'user_permissions': [
        {
          'id': 28,
          'name': 'Download',
          'createdAt': '2026-05-12T12:47:41.000Z',
          'updatedAt': '2026-05-12T12:47:41.000Z'
        }
      ],
    }
]

Request Example:

project_user = sa_client.list_users(
    email="test@superannotate.com",
)

Response Example:

[
    {
      'createdAt': '2026-05-19T08:28:55.000Z',
      'custom_fields': {},
      'email': 'test@superannotate.com',
      'id': 1622408,
      'role': 'Contributor',
      'state': 'Confirmed',
      'team_id': 32022,
      'updatedAt': '2026-05-19T08:28:55.000Z',
      'user_permissions': [
        {
          'id': 21,
          'name': 'Remove Contributors from team',
          'createdAt': '2026-05-12T12:47:41.000Z',
          'updatedAt': '2026-05-12T12:47:41.000Z'
        },
        {
          'id': 22,
          'name': 'View Contributors’ scores',
          'createdAt': '2026-05-12T12:45:41.000Z',
          'updatedAt': '2026-05-12T12:46:41.000Z'
        },
      ],
    }
]

SAClient.remove_users(users)#

Allows removing users from the team.

Parameters:: users (Union[List[int], List[str]]) – A list of emails or IDs of the users.
Return type:: None:

Request Example:

sa_client.remove_users(users=["example@gmail.com","example1@gmail.com"])

SAClient.pause_user_activity(pk, projects)#

Block the team contributor from requesting items from the projects.

Parameters:

pk (str or int) – The email address or user ID of the team contributor.
projects (Union[List[int], List[str], Literal["*"]]) – A list of project names or IDs from which the user should be blocked. The special value “*” means block access to all projects

SAClient.resume_user_activity(pk, projects)#

Resume the team contributor from requesting items from the projects.

Parameters:

pk (str or int) – The email address or user ID of the team contributor.
projects (Union[List[int], List[str], Literal["*"]]) – A list of project names or IDs from which the user should be resumed. The special value “*” means resume access to all projects

SAClient.get_user_scores(project, item, scored_user, *, score_names=None)#

Retrieve score metadata for a user for a specific item in a specific project.

Parameters:

project (Union[str, int, Tuple[int, int], Tuple[str, str]]) – Project and folder as a tuple, folder is optional.
item (Union[str, int]) – The unique ID or name of the item.
scored_user (str) – The email address of the project user.
score_names (Optional[List[str]]) – A list of score names to filter by. If None, returns all scores.

Returns:

A list of dictionaries containing score metadata for the user.

Return type:

list of dicts

Request Example:

sa_client.get_user_scores(
    project=("my_multimodal", "folder1"),
    item="item1",
    scored_user="example@superannotate.com",
    score_names=["Accuracy Score", "Speed"]
)

Response Example:

[
    {
        "createdAt": "2024-06-01T13:00:00",
        "updatedAt": "2024-06-01T13:00:00",
        "id": 3217575,
        "name": "Accuracy Score",
        "value": 98,
        "weight": 4,
    },
    {
        "createdAt": "2024-06-01T13:00:00",
        "updatedAt": "2024-06-01T13:00:00",
        "id": 5657575,
        "name": "Speed",
        "value": 9,
        "weight": 0.4,
    },
]

SAClient.set_user_scores(project, item, scored_user, scores)#

Assign score metadata for a user in a scoring component.

Parameters:

project (Union[str, int, Tuple[int, int], Tuple[str, str]]) – Project and folder as a tuple, folder is optional.
item (Union[str, int]) – The unique ID or name of the item.
scored_user (str) – Set the email of the user being scored.
scores (List[Dict[str, Any]) –
A list of dictionaries containing the following key-value pairs:
- component_id (str): The component_id of the score (required).
- value (Any): The score value (required).
- weight (Union[float, int], optional): The weight of the score. Defaults to 1 if not provided.
Example:
```
scores = [
    {
        "component_id": "<component_id_for_score>",  # str (required)
        "value": 90,      # Any (required)
        "weight": 1       # Union[float, int] (optional, defaults to 1.0 if not provided)
    }
]
```

Request Example:

sa_client.set_user_scores(
    project=("my_multimodal", "folder1"),
    item_=12345,
    scored_user="example@superannotate.com",
    scores=[
        {"component_id": "r_kfrp3n", "value": 90},
        {"component_id": "h_jbrp4v", "value": 9, "weight": 4.0},
        {"component_id": "m_kf8pss", "value": None, "weight": None},
    ]
)

SAClient.set_contributors_categories(project, contributors, categories)#

Assign one or more categories to a contributor with an assignable role (Annotator, QA, or custom role) in a Multimodal project. Project Admins are not eligible for category assignments. “*” in the category list will match all categories defined in the project.

Parameters:

project (Union[NotEmptyStr, int]) – The name or ID of the project.
contributors (List[Union[int, str]]) – A list of emails or IDs of the contributor.
categories (Union[List[str], Literal["*"]]) – A list of category names to assign. Accepts “*” to indicate all available categories in the project.

Request Example:

sa_client.set_contributor_categories(
    project="product-review-mm",
    contributors=["test@superannotate.com","contributor@superannotate.com"],
    categories=["Shoes", "T-Shirt"]
)

sa_client.set_contributor_categories(
    project="product-review-mm",
    contributors=["test@superannotate.com","contributor@superannotate.com"]
    categories="*"
)

SAClient.remove_contributors_categories(project, contributors, categories)#

Remove one or more categories for a contributor. “*” in the category list will match all categories defined in the project.

Parameters:

project (Union[NotEmptyStr, int]) – The name or ID of the project.
contributors (List[Union[int, str]]) – A list of emails or IDs of the contributor.
categories (Union[List[str], Literal["*"]]) – A list of category names to remove. Accepts “*” to indicate all available categories in the project.

Request Example:

sa_client.remove_contributor_categories(
    project="product-review-mm",
    contributors=["test@superannotate.com","contributor@superannotate.com"],
    categories=["Shoes", "T-Shirt", "Jeans"]
)

sa_client.remove_contributor_categories(
    project="product-review-mm",
    contributors=["test@superannotate.com","contributor@superannotate.com"]
    categories="*"
)

SAClient.grant_team_user_permissions(permissions, user)#

Grants permissions for a team user. Accepts “*” to indicate all available team-level permissions based on the user’s role.

Parameters:

permissions (Union[List[str], Literal["*"]]) –
Specifies which permissions to grant. Accepts “*” to indicate all available team user permissions.
Possible values are
- ”Access team API keys”: Only for Team Admins. Allows Team Admins to create, rotate, and revoke team API keys which have full Team Admin permissions. If this permission is set, it will automatically grant access to all the other admin permissions.
- ”Access Orchestrate”: Only for Team Admins. Allows Team Admins to create and monitor Orchestrate pipelines, as well as access Secrets and Proxies.
- ”Revoke members’ personal API keys”: Only for Team Admins. Allows Team Admins to revoke personal API keys generated by other members.
- ”Manage Contributors’ permissions”: Only for Team Contributors. Grants all contributor permissions and the ability to manage other contributors’ permissions. If this permission is set, it will automatically grant access to all the other contributor permissions.
- ”Invite Contributors to team”: Only for Team Contributors. Allows inviting contributors to the team.
- ”Remove Contributors from team”: Only for Team Contributors. Allows removing contributors from the team.
- ”View Contributors’ scores”: Only for Team Contributors. Allows viewing contributors’ scores.
- ”View Contributors’ custom field values”: Only for Team Contributors. Allows viewing contributors’ custom field values.
- ”Edit Contributors’ custom field values”: Only for Team Contributors. Allows editing contributors’ custom field values. If this permission is set, it will automatically grant access to “View Contributors’ custom field values” permission.
- ”Access Workload management”: Only for Team Contributors. Allows accessing Workload management.
user (Union[int, str]) – Team user ID or email to grant permissions to.

Return type:

None

Raises:

AppException – If permissions are empty or the user is not found.

Request Example:

# To grant a specific permission by email:
sa_client.grant_team_user_permissions(
    permissions=["Access team API keys"],
    user="test@superannotate.com"
)

# To grant all permissions by team user ID:
sa_client.grant_team_user_permissions(
    permissions="*",
    user=124341
)

# Example when granting "Edit Contributors' custom field values" permission
sa_client.grant_team_user_permissions(
    permissions=["Edit Contributors' custom field values"],
    user="test@superannotate.com"
)

# Example when granting "Manage Contributors' permissions" permission
sa_client.grant_team_user_permissions(
    permissions=["Manage Contributors' permissions"],
    user="test@superannotate.com"
)

SAClient.revoke_team_user_permissions(permissions, user)#

Revokes permissions for a team user. Accepts “*” to indicate all available team-level permissions based on the user’s role.

Parameters:

permissions (Union[List[str], Literal["*"]]) –
Specifies which permissions to revoke. Accepts “*” to indicate all available team user permissions. Possible values are the same as for grant_team_user_permissions().
The following rules apply when revoking:
- ”Access team API keys” grants every other Team Admin permission, so no Team Admin permission can be revoked while it is still granted; revoke “Access team API keys” first.
- ”Manage Contributors’ permissions” grants every other Team Contributor permission, so no Team Contributor permission can be revoked while it is still granted; revoke “Manage Contributors’ permissions” first.
- Revoking either of the above revokes only that permission; the permissions it implied stay granted.
- Revoking “View Contributors’ custom field values” will also revoke “Edit Contributors’ custom field values”.
user (Union[int, str]) – Team user ID or email to revoke permissions from.

Return type:

None

Raises:

AppException – If permissions are empty or the user is not found.

Request Example:

# To revoke a specific permission by email:
sa_client.revoke_team_user_permissions(
    permissions=["Remove Contributors from team"],
    user="contributor@superannotate.com"
)

# To revoke all permissions by team user ID:
sa_client.revoke_team_user_permissions(
    permissions="*",
    user=124341
)

# Example when revoking "View Contributors' custom field values" permission
sa_client.revoke_team_user_permissions(
    permissions=["View Contributors' custom field values"],
    user="test@superannotate.com"
)

# Example when revoking "Manage Contributors' permissions" permission
sa_client.revoke_team_user_permissions(
    permissions=["Manage Contributors' permissions"],
    user="test@superannotate.com"
)