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:

client.list_workflows() 

Response Example:

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

SAClient.get_integrations()#

Get all integrations per team

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

Request Example:

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

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:

client.set_contributor_categories( project="product-review-mm", contributors=["test@superannotate.com","contributor@superannotate.com"], categories=["Shoes", "T-Shirt"] ) 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:

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