## Retrieving users and groups

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/python/users-groups/how-tos/retrieve-users-groups

> Retrieve users and groups in Atlan using AtlanUser and AtlanGroup with the Python SDK (pyatlan). Filter by name, email, or role.

# AtlanUser: retrieve users and groups

Use `AtlanUser` and `AtlanGroup` in the Atlan Python SDK to programmatically retrieve users and groups from your Atlan environment.

You can retrieve users and groups through different helper methods.

## Retrieve all groups

For example, to retrieve all groups in Atlan:

### Java

```java showLineNumbers title="Retrieve all groups"
List groups = AtlanGroup.list(client); // (1)
for (AtlanGroup group : groups)
```

1. You can retrieve all groups in Atlan using the `AtlanGroup.list()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the groups to do whatever you like with them.

### Python

```python showLineNumbers title="Retrieve all groups"

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

groups = client.group.get_all( # (1)
 limit=10, 
 offset=1, 
 sort="createdAt", 
 columns=["roles", "path"])
for group in groups: # (2)
 # Do something with the group...
```

1. The `get_all()` method retrieves all groups defined in Atlan. Returns a GroupResponse object. Optional parameters include:
 - *(Optional)* **`limit`**: Specifies the maximum number of results to return. Defaults to `20`.
 - *(Optional)* **`offset`**: Indicates the starting point for the results when paging. Defaults to `0`.
 - *(Optional)* **`sort`**: Allows sorting by a specific property, such as `"createdAt"`.
 - *(Optional)* **`columns`**: Restricts the fields returned for each group, providing column projection support. Example: `["roles", "path"]`.

2. This is the pattern for iterating through all results (across pages) covered in the [Searching for assets](https://docs.atlan.com/llms/platform/python/search-assets/llms.txt) portion of the SDK documentation.

### Kotlin

```kotlin showLineNumbers title="Retrieve all groups"
val groups = AtlanGroup.list(client) // (1)
for (group in groups)
```

1. You can retrieve all groups in Atlan using the `AtlanGroup.list()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the groups to do whatever you like with them.

### Go

```go showLineNumbers title="Retrieve all groups"
groups, atlanErr := ctx.GroupClient.GetAll( // (1)
 10,
 1,
 "createdAt",
)
for _, group := range groups { // (2)
 // Do Something with the group...
}
```

1. The `GetAll()` method retrieves all groups defined in Atlan. Optional parameters include:
 - *(Optional)* **`limit`**: Specifies the maximum number of results to return. Defaults to `20`.
 - *(Optional)* **`offset`**: Indicates the starting point for the results when paging. Defaults to `0`.
 - *(Optional)* **`sort`**: Allows sorting by a specific property, such as `"createdAt"`.

2. You can then iterate through the groups to do whatever you like with them.

### Raw REST API

```json showLineNumbers title="GET /api/service/v2/groups?sort=createdAt&imit=10&offset=0&columns=path&columns=roles"
// (1)
```

1. All details are in the URL itself.

 :::tip[Paging results]
Note that you have a `limit` to control page size, and an `offset` to control where to start a page.
 :::

## Retrieve group by name

To retrieve a specific group in Atlan by its name:

### Java

```java showLineNumbers title="Retrieve group by name"
List list = AtlanGroup.get(client, "Example"); // (1)
AtlanGroup group = list.get(0); // (2)
```

1. You can retrieve a specific group by its name using the `AtlanGroup.get()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

 :::tip[Still returns a list]
Note that this still returns a list of groups, as it actually runs a `contains` search for the specified name. You could therefore use this same method to retrieve many groups that all follow the same naming convention, for example.
 :::
2. If you were expecting only a single group to match, however, you can still retrieve that from the list directly, of course.

### Python

```python showLineNumbers title="Retrieve group by name"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
groups = client.group.get_by_name("Example") # (1)
group = groups.records[0] # (2)
```

1. You can retrieve a specific group by its name using the `group.get_by_name()` method. Returns a GroupResponse object.

 :::tip[Still returns a list]
Note that this still returns a list of groups, as it actually runs a `contains` search for the specified name. You could therefore use this same method to retrieve many groups that all follow the same naming convention, for example.
 :::
2. If you were expecting only a single group to match, however, you can still retrieve that from the list directly, of course.

### Kotlin

```kotlin showLineNumbers title="Retrieve group by name"
val list = AtlanGroup.get(client, "Example") // (1)
val group = list[0] // (2)
```

1. You can retrieve a specific group by its name using the `AtlanGroup.get()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

 :::tip[Still returns a list]
Note that this still returns a list of groups, as it actually runs a `contains` search for the specified name. You could therefore use this same method to retrieve many groups that all follow the same naming convention, for example.
 :::
2. If you were expecting only a single group to match, however, you can still retrieve that from the list directly, of course.

### Go

```go showLineNumbers title="Retrieve group by name"
groups, atlanErr := ctx.GroupClient.GetByName("Example", 20, 0) // (1)
group := groups[0] // (2)
```

1. You can retrieve a specific group by its name using the `GroupClient.GetByName()` method. You can also set the limit (default is 20) and offset (default is 0).

 :::tip[Still returns a list]
Note that this still returns a list of groups, as it actually runs a `contains` search for the specified name. You could therefore use this same method to retrieve many groups that all follow the same naming convention, for example.
 :::
2. If you were expecting only a single group to match, however, you can still retrieve that from the list directly, of course.

### Raw REST API

```json showLineNumbers title="GET /api/service/groups?filter=%7B%22%24and%22%3A[%7B%22alias%22%3A%7B%22%24ilike%22%3A%22%25Example%25%22%7D%7D]%7D"
// (1)
```

1. All details are in the URL itself.

 :::tip[URL-encoded filter]
Note that the filter is URL-encoded. Decoded it would be: `{"$and":[{"alias":{"$ilike":"%Example%"}}]}`
 :::

## Retrieve all users

To retrieve all users in Atlan:

### Java

```java showLineNumbers title="Retrieve all users"
List users = AtlanUser.list(client); // (1)
for (AtlanUser user : users)
```

1. You can retrieve all users in Atlan using the `AtlanUser.list()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the users to do whatever you like with them.

### Python

```python showLineNumbers title="Retrieve all users"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
users = client.user.get_all() # (1)
for user in users: # (2)
 # Do something with the user...
```

1. You can retrieve all users in Atlan using the `get_all()` method under the `user` attribute of the AtlanClient instance. Returns a UserResponse object.
2. This is the pattern for iterating through all results (across pages) covered in the [Searching for assets](https://docs.atlan.com/llms/platform/python/search-assets/llms.txt) portion of the SDK documentation.

### Kotlin

```kotlin showLineNumbers title="Retrieve all users"
val users = AtlanUser.list(client) // (1)
for (user in users)
```

1. You can retrieve all users in Atlan using the `AtlanUser.list()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the users to do whatever you like with them.

### Go

```go showLineNumbers title="Retrieve all users"
users, atlanErr := ctx.UserClient.GetAll(20, 0, "") // (1)
for _, user := range users { // (2)
 // Do something with the user...
}
```

1. You can retrieve all users in Atlan using the `GetAll()` method under the `user` attribute of the AtlanClient instance. You can also set the limit (default is 20), offset (default is 0) and sort (default is by username).
2. You can then iterate through the users to do whatever you like with them.

### Raw REST API

```json showLineNumbers title="GET /api/service/users?sort=username&limit=100&offset=0"
// (1)
```

1. All details are in the URL itself.

 :::tip[Paging results]
Note that you have a `limit` to control page size, and an `offset` to control where to start a page.
 :::

## Retrieve user by username

To retrieve a specific user in Atlan by their username:

### Java

```java showLineNumbers title="Retrieve user by username"
AtlanUser user = AtlanUser.getByUsername(client, "jdoe"); // (1)
```

1. You can retrieve a specific user by their username using the `AtlanUser.getByUsername()` method. This runs an exact match for the provided username, so only returns a single user (if found). Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Python

```python showLineNumbers title="Retrieve user by username"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
user = client.user.get_by_username("jdoe") # (1)
```

1. You can retrieve a specific user by their username using the `user.get_by_username()` method. This runs an exact match for the provided username, so only returns a single user (if found).

### Kotlin

```kotlin showLineNumbers title="Retrieve user by username"
val user = AtlanUser.getByUsername(client, "jdoe") // (1)
```

1. You can retrieve a specific user by their username using the `AtlanUser.getByUsername()` method. This runs an exact match for the provided username, so only returns a single user (if found). Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

### Go

```go showLineNumbers title="Retrieve user by username"
users, atlanErr := ctx.UserClient.GetByUsername("jdoe") // (1)
```

1. You can retrieve a specific user by their username using the `UserClient.GetByUsername()` method. This runs an exact match for the provided username, so only returns a single user (if found).

### Raw REST API

```json showLineNumbers title="GET /api/service/users?filter=%7B%22username%22%3A%22jdoe%22%7D"
// (1)
```

1. All details are in the URL itself.

 :::tip[URL-encoded filter]
Note that the filter is URL-encoded. Decoded it would be: `{"username":"jdoe"}`
 :::

## Retrieve user by email

To retrieve a specific user in Atlan by their email address:

### Java

```java showLineNumbers title="Retrieve user by username"
List users = AtlanUser.getByEmail(client, "@example.com"); // (1)
AtlanUser user = users.get(0); // (2)
```

1. You can retrieve a specific user by their email address using the `AtlanUser.getByEmail()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

 :::tip[Still returns a list]
Note that this still returns a list of users, as it actually runs a `contains` search for the specified email address. You could therefore use this same method to retrieve many users that all have the same email domain, for example.
 :::
2. If you were expecting only a single user to match, however, you can still retrieve that from the list directly, of course.

### Python

```python showLineNumbers title="Retrieve user by username"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
users = client.user.get_by_email("@example.com") # (1)
user = users.records[0] # (2)
```

1. You can retrieve a specific user by their email address using the `user.get_by_email()` method. Returns a UserResponse object.

 :::tip[Still returns a list]
Note that this still returns a list of users, as it actually runs a `contains` search for the specified email address. You could therefore use this same method to retrieve many users that all have the same email domain, for example.
 :::
2. If you were expecting only a single user to match, however, you can still retrieve that from the list directly, of course.

### Kotlin

```kotlin showLineNumbers title="Retrieve user by username"
val users = AtlanUser.getByEmail(client, "@example.com") // (1)
val user = users[0] // (2)
```

1. You can retrieve a specific user by their email address using the `AtlanUser.getByEmail()` method. Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.

 :::tip[Still returns a list]
Note that this still returns a list of users, as it actually runs a `contains` search for the specified email address. You could therefore use this same method to retrieve many users that all have the same email domain, for example.
 :::
2. If you were expecting only a single user to match, however, you can still retrieve that from the list directly, of course.

### Go

```go showLineNumbers title="Retrieve user by username"
users, atlanErr := ctx.UserClient.GetByEmail("@example.com", 20, 0) // (1)
user := users[0] // (2)
```

1. You can retrieve a specific user by their email address using the `UserClient.GetByEmail()` method.

 :::tip[Still returns a list]
Note that this still returns a list of users, as it actually runs a `contains` search for the specified email address. You could therefore use this same method to retrieve many users that all have the same email domain, for example.
 :::
2. If you were expecting only a single user to match, however, you can still retrieve that from the list directly, of course.

### Raw REST API

```json showLineNumbers title="GET /api/service/users?filter=%7B%22email%22%3A%7B%22%24ilike%22%3A%22%25%40example.com%25%22%7D%7D"
// (1)
```

1. All details are in the URL itself.

 :::tip[URL-encoded filter]
Note that the filter is URL-encoded. Decoded it would be: `{"email":{"$ilike":"%@example.com%"}}`
 :::

## Retrieve multiple users

### By usernames

To retrieve multiple users in Atlan by their usernames:

### Java

```java showLineNumbers title="Retrieve users by usernames"
List users = client.users.getByUsernames(
 List.of("john.doe", "jane.doe")
 ); // (1)
```

1. Retrieve users with specified usernames using the `users.getByUsernames()` method. This method performs an exact match for the provided username in the list.

### Python

```python showLineNumbers title="Retrieve users by usernames"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
users = client.user.get_by_usernames(['john.doe', 'jane.doe']) # (1)
for user in users: # (2)
 # Do something with the user...
```

1. Retrieve users with specified usernames using the `user.get_by_usernames()` method.
This method performs an exact match for the provided username in the list. Returns a UserResponse object.
2. This is the pattern for iterating through all results (across pages) covered in the [Searching for assets](https://docs.atlan.com/llms/platform/python/search-assets/llms.txt) portion of the SDK documentation.

### Kotlin

```kotlin showLineNumbers title="Retrieve users by usernames"
val users = client.users.getByUsernames(
 listOf("john.doe", "jane.doe")
 ); // (1)
```

1. Retrieve users with specified usernames using the `users.getByUsernames()` method. This method performs an exact match for the provided username in the list.

### Go

```go showLineNumbers title="Retrieve users by usernames"
users, atlanErr := ctx.UserClient.GetByUsernames([]string{"john.doe", "jane.doe"}, 20, 0) // (1)
```

1. Retrieve users with specified usernames using the `UserClient.GetByUsernames()` method.
This method performs an exact match for the provided username in the list.

### Raw REST API

```json showLineNumbers title="GET /api/service/users?filter={%22username%22:{%22$in%22:[%22john.doe%22,%22jane.doe%22]}}"
// (1)
```

1. All details are in the URL itself.

 :::tip[URL-encoded filter]
Note that the filter is URL-encoded. Decoded it
would be: `{"username":{"$in":["john.doe","jane.doe"]}}`
 :::

### By emails

To retrieve multiple users in Atlan by their emails:

### Java

```java showLineNumbers title="Retrieve users by emails"
List users = client.users.getByEmails(
 List.of("john@atlan.com", "jane@atlan.com")
 ); // (1)
```

1. Retrieve users with specified emails using the `users.getByEmails()` method. This method performs an exact match for the provided email in the list.

### Python

```python showLineNumbers title="Retrieve users by emails"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
users = client.user.get_by_emails(['john@atlan.com', 'jane@atlan.com']) # (1)
for user in users: # (2)
 # Do something with the user...
```

1. Retrieve users with specified emails using the `user.get_by_emails()` method.
This method performs an exact match for the provided email in the list. Returns a UserResponse object.
2. This is the pattern for iterating through all results (across pages) covered in the [Searching for assets](https://docs.atlan.com/llms/platform/python/search-assets/llms.txt) portion of the SDK documentation.

### Kotlin

```kotlin showLineNumbers title="Retrieve users by emails"
val users = client.users.getByEmails(
 listOf("john@atlan.com", "jane@atlan.com")
 ); // (1)
```

1. Retrieve users with specified emails using the `users.getByEmails()` method. This method performs an exact match for the provided email in the list.

### Go

```go showLineNumbers title="Retrieve users by emails"
users, atlanErr := ctx.UserClient.GetByEmails([]string{"john@atlan.com", "jane@atlan.com"}, 20, 0) // (1)
```

1. Retrieve users with specified emails using the `UserClient.GetByEmails()` method.
This method performs an exact match for the provided email in the list.

### Raw REST API

```json showLineNumbers title="GET /api/service/users?filter={%22email%22:{%22$in%22:[%22john@atlan.com%22,%20%22jane@atlan.com%22]}}"
// (1)
```

1. All details are in the URL itself.

 :::tip[URL-encoded filter]
Note that the filter is URL-encoded. Decoded it
would be: `{"email":{"$in":["john@atlan.com","jane@atlan.com"]}}`
 :::

## Retrieve user group membership

### Retrieve groups for user

To retrieve the groups a user is a member of:

### Java

```java title="Retrieve groups for a user"
GroupResponse response = user.fetchGroups(client); // (1)
for (AtlanGroup group : response)
```

1. You can retrieve the groups the user is a member of using the `fetchGroups()` method, after you have an `AtlanUser` object (for example, by first retrieving it). Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the groups the user is a member of.

### Python

```python title="Retrieve groups for a user"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.user.get_groups(user.id) # (1)
for group in response: # (2)
 # Do something with each group...
```

1. You can retrieve the groups the user is a member of using the
`user.get_groups()` method, by providing the GUID of the user.
2. You can then iterate through the groups the user is a member of.

### Kotlin

```kotlin title="Retrieve groups for a user"
val response = user.fetchGroups(client) // (1)
for (group in response)
```

1. You can retrieve the groups the user is a member of using the `fetchGroups()` method, after you have an `AtlanUser` object (for example, by first retrieving it). Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the groups the user is a member of.

### Go

```go title="Retrieve groups for a user"
response, atlanErr := ctx.UserClient.GetGroups(user.ID, nil) // (1)
for _, group := range response { // (2)
 // Do something with each group...
}
```

1. You can retrieve the groups the user is a member of using the
`UserClient.GetGroups()` method, by providing the GUID of the user.
2. You can then iterate through the groups the user is a member of.

### Raw REST API

```json showLineNumbers title="GET /api/service/users/f06122f4-7279-4e42-b9e0-46f9b470e659/groups"
// (1)
```

1. All details are in the URL itself.

 :::tip[User ID in the URL]
Note that you must provide the unique ID (GUID) of the user to retrieve its associated groups.
 :::

### Retrieve users in group

To retrieve the users that are members of a group:

### Java

```java title="Retrieve users in a group"
UserResponse response = group.fetchUsers(client); // (1)
for (AtlanUser user : response)
```

1. You can retrieve the users a group has as members using the `fetchUsers()` method, after you have an `AtlanGroup` object (for example, by first retrieving it). Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the users that are members of the group.

### Python

```python title="Retrieve users in a group"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
response = client.group.get_members(group.id) # (1)
for user in response: # (2)
 # Do something with each user...
```

1. You can retrieve the users a group has as members using the
`group.get_members()` method, by providing the GUID of the group.
2. You can then iterate through the users that are members of the group.

### Kotlin

```kotlin title="Retrieve users in a group"
val response = group.fetchUsers(client) // (1)
for (user in response)
```

1. You can retrieve the users a group has as members using the `fetchUsers()` method, after you have an `AtlanGroup` object (for example, by first retrieving it). Because this operation will retrieve information from Atlan, you must [provide it an `AtlanClient`](https://docs.atlan.com/llms/platform/python/set-up-sdk/llms.txt) through which to connect to the tenant.
2. You can then iterate through the users that are members of the group.

### Go

```go title="Retrieve users in a group"
response, atlanErr := ctx.GroupClient.GetMembers(group.ID, nil)
for _, user := range response {
 // Do something with each user
}
```

1. You can retrieve the users a group has as members using the
`GroupClient.GetMembers()` method, by providing the GUID of the group.
2. You can then iterate through the users that are members of the group.

### Raw REST API

```json showLineNumbers title="GET /api/service/groups/e79cb8eb-2bb6-4821-914c-f8dfd21fedc7/members"
// (1)
```

1. All details are in the URL itself.

 :::tip[Group ID in the URL]
Note that you must provide the unique ID (GUID) of the group to retrieve its associated members.
 :::

---