> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Users

> List all users with optional filtering and pagination

# List Users

List all users with optional filtering and pagination.

## Query Parameters

**limit** `integer` (default: 10)

Maximum number of results to return (max: 1000000).

**before** `string`

Cursor for backward pagination.

**after** `string`

Cursor for forward pagination.

**fields** `string`

Comma-separated list of fields to include: `teams`, `roles`, `personas`, `domains`, `follows`, `owns`. See [Supported Fields](#supported-fields) below.

**include** `string` (default: non-deleted)

Include `all`, `deleted`, or `non-deleted` entities.

**isBot** `boolean`

Filter by bot status. Set to `true` to list only bot accounts, `false` for human users only.

**isAdmin** `boolean`

Filter by admin status. Set to `true` to list only admin users.

**team** `string`

Filter by team name. Returns only users belonging to the specified team.

```python GET /v1/users theme={null}
from metadata.sdk import configure
from metadata.sdk.entities import Users

configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="your-jwt-token"
)

# List first page
users = Users.list(limit=50)
for user in users.entities:
    print(f"{user.fullyQualifiedName.root}")

# List all with auto-pagination
for user in Users.list_all():
    print(f"{user.fullyQualifiedName.root}")

# Filter by team with fields
users = Users.list(
    filters={"team": "Sales"},
    fields=["teams", "roles", "domains"],
    limit=50
)

for user in users.entities:
    print(f"{user.fullyQualifiedName.root}")
    if user.teams:
        print(f"  Teams: {[t.name for t in user.teams.root]}")
    if user.roles:
        print(f"  Roles: {[r.name for r in user.roles.root]}")

# Filter bot accounts
bots = Users.list(filters={"isBot": "true"}, limit=50)
```

```java GET /v1/users theme={null}
import org.openmetadata.sdk.models.ListParams;

// client is an initialized OpenMetadataClient.
// List first page
var params = new ListParams().setLimit(50);
var page = client.users().list(params);
for (var item : page.getData()) {
    System.out.println(item.getFullyQualifiedName());
}

// Filter by team with fields
var filtered = new ListParams()
    .addFilter("team", "Sales")
    .setFields("teams,roles,domains")
    .setLimit(50);
var filteredPage = client.users().list(filtered);
for (var item : filteredPage.getData()) {
    System.out.println(item.getFullyQualifiedName());
}
```

```bash GET /v1/users theme={null}
# List all
curl "{base_url}/api/v1/users?limit=50" \
  -H "Authorization: Bearer {access_token}"

# Filter by team
curl "{base_url}/api/v1/users?team=Sales&limit=50" \
  -H "Authorization: Bearer {access_token}"

# With fields
curl "{base_url}/api/v1/users?fields=teams,roles,domains&limit=50" \
  -H "Authorization: Bearer {access_token}"

# Filter bot accounts
curl "{base_url}/api/v1/users?isBot=true&limit=50" \
  -H "Authorization: Bearer {access_token}"

# Filter admin users
curl "{base_url}/api/v1/users?isAdmin=true&limit=50" \
  -H "Authorization: Bearer {access_token}"
```

```json Response theme={null}
{
  "data": [
    {
      "id": "77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
      "name": "aaron_johnson0",
      "fullyQualifiedName": "aaron_johnson0",
      "displayName": "Aaron Johnson",
      "version": 0.1,
      "updatedAt": 1769982624214,
      "updatedBy": "admin",
      "email": "aaron_johnson0@gmail.com",
      "href": "http://localhost:8585/api/v1/users/77655e6e-ad33-49da-bbca-db4ba4d4e2cd",
      "isBot": false,
      "isAdmin": false,
      "allowImpersonation": false,
      "teams": [
        {
          "id": "7a2b921b-f623-4eb5-9736-649788ad842c",
          "type": "team",
          "name": "Sales",
          "fullyQualifiedName": "Sales",
          "displayName": "Sales",
          "deleted": false
        }
      ],
      "personas": [],
      "deleted": false,
      "roles": [
        {
          "id": "761c2bb2-0b77-4bc5-9af9-cf89536d6a12",
          "type": "role",
          "name": "DataSteward",
          "fullyQualifiedName": "DataSteward",
          "displayName": "Data Steward",
          "deleted": false
        }
      ],
      "domains": []
    }
  ],
  "paging": {
    "after": "...",
    "total": 117
  }
}
```

***

## Returns

Returns a paginated list of user objects. By default, only basic fields are included. Use the `fields` parameter to request additional data.

## Response

**data** `array`

Array of user objects.

**properties**

**id** `string`

Unique identifier for the user (UUID format).

**name** `string`

Username.

**fullyQualifiedName** `string`

Fully qualified name (same as `name` for users).

**displayName** `string`

Human-readable display name.

**email** `string`

Email address of the user.

**isBot** `boolean`

Whether this user is a bot account.

**isAdmin** `boolean`

Whether this user has admin privileges.

**teams** `array`

Teams the user belongs to. Only included when `fields` contains `teams`.

**roles** `array`

Roles assigned to the user. Only included when `fields` contains `roles`.

**personas** `array`

Personas assigned to the user. Only included when `fields` contains `personas`.

**domains** `array`

Domain assignments for governance. Only included when `fields` contains `domains`.

**follows** `array`

Entities the user follows. Only included when `fields` contains `follows`.

**owns** `array`

Entities owned by the user. Only included when `fields` contains `owns`.

**paging** `object`

Pagination information.

**properties**

**total** `integer`

Total count of users matching the query.

**after** `string`

Cursor for the next page of results. Null if this is the last page.

**before** `string`

Cursor for the previous page of results. Null if this is the first page.

***

## Supported Fields

The following fields can be requested via the `fields` query parameter:

| Field | Description |
| - | - |
| `teams` | Teams the user belongs to |
| `roles` | Roles assigned to the user |
| `personas` | Personas assigned to the user |
| `domains` | Domain assignments for governance |
| `follows` | Entities the user follows |
| `owns` | Entities owned by the user |

***

## Error Handling

| Code | Error Type | Description |
| - | - | - |
| `401` | `UNAUTHORIZED` | Invalid or missing authentication token |
| `403` | `FORBIDDEN` | User lacks permission to list users |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.