# Search groups > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/rest-apiv2-groups-search # Search groups The `[/groups/search](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups)` API endpoint is used to retrieve details about ThooughtSpot groups (referred to as user groups or with the `USER_GROUP` value in the API), with many specific filtering capabilities for answering a number of relevant questions about groups. You can search for the `USER_GROUP` type using `metadata/search`, but `groups/search` provides considerably more control. The overall structure of `groups/search` request is [described as a combination of objects](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fstructures%2Fapi-rest-20-groups-search-request). Note that many parameters in the request are **optional**, and leaving the parameter name out entirely has a different effect from including the parameter and specific values. Throughout this article, requests and responses will be shown as JSON, without any of the code to send the requests. The v2.0 Playground generates requests that always include the default values for any parameters that have them, but this article excludes them. Assume every request you see has the following parameters in addition to what is shown: ```JSON { "record_offset" : 0, "record_size": 10 } ``` > **WARNING:** Do not set record\_size to -1. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit record\_size and iterate through pages programmatically. ## Response format The response from any call to `groups/search` will resemble the following: ```JSON [ { "author_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "complete_detail": true, "content": NULL, "creation_time_in_millis": 1354006445722, "default_liveboards": [], "deleted": false, "deprecated": false, "description": NULL, "display_name": "System Management Group", "external": false, "generation_number": 867825, "hidden": false, "id": "179d8867-cf36-4a8d-a019-63a226fd3196", "index": 3, "index_version": 867825, "metadata_version": 0, "modification_time_in_millis": 1354006445722, "modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "name": "System", "orgs": NULL, "owner_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "parent_type": "GROUP", "privileges": [], "sub_groups": [], "system_group": true, "tags": [], "type": "LOCAL_GROUP", "users": [ { "id": "67e15c06-d153-4924-a4cd-ff615393b60f", "name": "nick.cooper" }, ... ], "visibility": "SHARABLE", "roles": null } ... ] ``` ## Lists of metadata The `/groups/search` API performs listing functions when you do not send specific object IDs as part of your request. Note you must send some request in the body of the POST, even if this is only `{ }`. The basic metadata selectors are placed in the `metadata` parameter as an array of [Metadata List objects](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fstructures%2Fmetadata-list-item-input). For example, to see **all groups**, you can simply send the `record_offset` and `record_size` parameters: ```JSON { "record_offset": 0, "record_size": 100000 } ``` ## Retrieve specific objects Several parameters allow referencing a group object directly. The `group_identifier` parameter takes either the group name or group GUID: ```JSON { "group_identifier": "Marketing Team" } ``` - `display_name` checks against the visible display name that shows within the ThoughtSpot UI. - `description` is also available as a filtering parameter. ## Filtering and sorting ### sort\_options The `sort_options` parameter requires [Sort Options](https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fenumerations%2Ffield-name) to sort on one field of the metadata response either in the ascending (`ASC`) or descending (`DESC`) order: ```JSON { "sort_options": { "field_name": "DISPLAY_NAME", "order": "ASC" } } ``` If you need multiple levels of sorting, you’ll have to parse the response programmatically and apply a sorting algorithm on the properties within each response item. ### user\_identifiers You can filter responses based on which users belong to a group. The `user_identifiers` parameter takes an array of strings of either **username** or **user GUID**. Note that users have a `display_name` property separate from **username** that cannot be used in the `user_identifiers` array. ```JSON { "user_identifiers" : [ "Developers" ] } ``` As with other filters that take arrays, the query treats multiple items as a logical OR operation. If you need to identify groups with an exact set of users, you’ll need to process the result and inspect the `users` array of each returned group object. ### privileges Responses can be filtered based on **privileges** assigned to the user. Privileges are assigned through groups directly or via roles on ThoughtSpot instances with the newer roles feature enabled. The array of privileges works as an OR condition, returning any group with any of the privileges listed. If you need to find a group with a set of privileges, you’ll have to check the `privileges` array for each group object in the response. ```JSON { "privileges": [ "DEVELOPER", "DATADOWNLOADING" ] } ``` ### visibility Every group has a `visibility` property which can either be `SHARABLE` or `NON_SHARABLE`. A `SHARABLE` group can have content shared by users who belong to the same `sharable` group. You can list groups with a specific visibility setting by specifying the `visibility` property in the request: ```JSON { "visibility": "SHARABLE" } ``` ### user\_identifiers You can filter responses based on which users belong to a group. The `user_identifiers` parameter takes an array of strings of either **username** or **user GUID**. Note that the `display_name` property is different from `username` and cannot be used in the `user_identifiers` array. ```JSON { "user_identifiers" : [ "Developers" ] } ``` ### type The `type` property tracks which authentication method was used to create a given group. The two options are `LOCAL_GROUP` and `LDAP_GROUP`. ```JSON { "type": "LDAP_GROUP" } ``` ### sub\_group\_identifiers Groups in ThoughtSpot can belong to other groups. The `sub_group_identifiers` parameter takes an array of strings of either group name or group GUID and returns a list of groups with those sub-groups. ```JSON { "sub_group_identifiers" : [ "A Sub Group Name" ] } ``` ### default\_liveboard\_identifiers The `default_liveboard_identifiers` parameter filters groups with the specified Liveboards set as default Liveboards for users in that group. The value can take the GUID of a Liveboard or its name, but because Liveboard names are not guaranteed to be unique, it is best to use the GUIDs of any specific Liveboards when using this filtering parameter: ```JSON { "default_liveboard_identifiers": ["a1fdcb4d-9cf9-466b-b866-22c53db9b1ac"] } ``` ### org\_identifiers On a ThoughtSpot instance with Orgs, a user can belong to multiple Orgs. The `org_identifiers` parameter takes an array of strings representing either Org names or Org ID. As with other filtering parameters that take arrays, the list of identifiers is handled as a logical OR, returning any users who belong to the specified identifiers. To filter the response to get a user that belongs to a particular set of Orgs, you will need to do additional processing on the result set to confirm the full set of Orgs matches: ```JSON { "org_identifiers": [ "Dev", "UAT" ] } ``` The `Orgs` key of each user item in the response contains the details of the Orgs, which can be read and compared to the set of Orgs you want to match for that user: ```JSON ... "orgs":[ { "id": 1568202965, "name": "Dev" }, { "id": 2004448319, "name": "Secondary" } ] ... ``` Note that the Org ID is an integer in this portion of the response. ### role\_identifiers On ThoughtSpot instances with the Role-Based Access Control(RBAC) feature enabled, you can use the `role_identifiers` parameter to send an array of either GUID or the name of the roles to which a given group is assigned.