# List group members

`GET /group.members`

## Description

List members in a group with their roles.

Apps may list members if one of the following conditions is true:
1. It is a public group in their Roam.
2. They are a member of the group.

**Required scope:** `group:read`

Every returned `userId` is a visible principal ID that resolves through
[`user.info`](/docs/api/user-info) with the same credentials. Use
`user.list?ids` for ordered bulk hydration.

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | query | string | Yes | Group ID. |
| `limit` | query | integer | No | The number of members to return per response. Default is 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Members retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `members` | GroupMember[] | No |  |
| `nextCursor` | string | No | Pagination cursor for fetching the next page of results |

**GroupMember** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `userId` | string | Yes | The user's unique identifier |
| `role` | "member" | "admin" | Yes | The member's role in the group |


#### Example Response

```json
{
  "members": [
    {
      "userId": "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
      "role": "member"
    },
    {
      "userId": "af6663d5-0f37-4105-95df-4fea20ef7c7c",
      "role": "admin"
    },
    {
      "userId": "f589a8cb-78ac-493e-8719-0fa8a22f65e0",
      "role": "member"
    }
  ],
  "nextCursor": "YzE6ZjU4OWE4Y2ItNzhhYy00OTNlLTg3MTktMGZhOGEyMmY2NWUw"
}
```

### 400 - Invalid request, e.g. group does not exist.

### 401 - Unauthorized.

### 403 - App does not have access to this group.

### 500 - An internal error occurred, including a group-member ID that cannot resolve as a visible principal. The endpoint does not return a partial page.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/group-members*