# List users

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

View users and pending invitations in the current workspace by page. You can filter by name, description, or membership status.

```text
POST https://moi.matrixorigin.cn/newmoi/user/list
```

## Preparation before calling

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md#manage-api-keys) and [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id) with access to the target workspace.

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Input example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/user/list" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20
  }'
```

:::::
:::::{tab-item} Parameter description

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | Page number. |
| `page_size` | integer | No | Number of items per page. |
| `filters` | object (array) | No | Filter conditions. |
| `filters[].name` | string | Yes | Filter field: `name`, `name_description`, or `status`. |
| `filters[].values` | string (array) | Yes | Filter values. The service uses the first value in each item. |

`name` performs a case-insensitive contains match on user names; `name_description` matches both user names and descriptions; `status` is an exact status match. To read the next page, increment `page` by 1 and retain the same filters. Stop when the cumulative number read reaches `data.total`, or when `data.user_list` is empty on the current page.

:::::
::::::
:::::::
## Successful response

On success, returns the total number of users matching the filters and the current page of data. Pending invitations can also appear in the list with a `pending` status.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "user_list": [
      {
        "id": "user-001",
        "iam_user_id": "iam-user-001",
        "name": "data_analyst",
        "status": "enabled",
        "created_at": "2026-08-01T09:00:00Z",
        "updated_at": "2026-08-21T09:00:00Z",
        "reserved": false,
        "role_list": [],
        "tag_list": []
      }
    ]
  }
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.total` | integer | Total number of users that match the filters. |
| `data.user_list` | object (array) | Users and pending invitations on the current page. |
| `data.user_list[].id` | string | User ID in the account system; it can be empty before a pending invitation has completed its mapping. |
| `data.user_list[].iam_user_id` | string | IAM user ID. |
| `data.user_list[].name` | string | User name in the workspace. |
| `data.user_list[].description` | string | User description; omitted when unset. |
| `data.user_list[].status` | string | User status: `enabled`, `disabled`, or `pending`. |
| `data.user_list[].created_at` | string | Creation time in RFC 3339 format. |
| `data.user_list[].updated_at` | string | Update time in RFC 3339 format. |
| `data.user_list[].reserved` | boolean | Whether this is a reserved user. |
| `data.user_list[].role_list` | object (array) | User's directly assigned roles. |
| `data.user_list[].tag_list` | object (array) | User tags. |
| `data.user_list[].github_login` | string | GitHub login; omitted when unset. |

:::::
::::::
:::::::

## Error response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "INVALID_ARGUMENT",
  "msg": "请求参数无效",
  "data": null
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Error message. |
| `data` | null | — |

:::::
::::::
:::::::

## Next steps

### Select a user

For user updates, deletion, status changes, role binding, or activity-record viewing, select a user whose invitation is complete. Entries still awaiting invitation acceptance cannot be used for subsequent user management operations.

### Confirm the invitation status

After creating a user, view the list to confirm that the invitation has become a manageable workspace user. Only users whose invitations are complete can be updated, deleted, assigned role bindings, or queried for activity records.