Team#

SAClient.get_team_metadata()#

Returns team metadata

Returns:: team metadata
Return type:: dict

SAClient.get_integrations()#

Get all integrations per team

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

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.search_team_contributors(email=None, first_name=None, last_name=None, return_metadata=True)#

Search for contributors in the team

Parameters:

email (str) – filter by email
first_name (str) – filter by first name
last_name (str) – filter by last name
return_metadata (bool) – return metadata of contributors instead of names

Returns:

metadata of found users

Return type:

list of dicts

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:

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:

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[typing_extensions.Literal[custom_fields]]) –
Specifies additional fields to be included in the response.

Possible values are
- ”custom_fields”: Includes custom fields and scores assigned to each user.
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 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}
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:

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,
    }
]

Request Example:

# Project level scores

scores = 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,
        "role": "Annotator",
        "state": "Confirmed",
        "team_id": 1234,
    }
]

Request Example:

# Team level scores

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

scores = 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,
    }
]

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, 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:

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, 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:

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},
    ]
)