# Get community users

Get one page of your community's traders, with their names, email, online status and last sign-in.

- Endpoint: `GET https://api.returning.ai/v1/communities/{communityId}/users`
- Section: Community / Members
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `None` (Any Community API key for this community works)
- Retries: Read-only; exact retries are safe
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/community-community-users/get-community-users

## When to use this

- You show a simple member list in your own admin tools, with who is online first.
- You want to see which of your traders are online right now.
- You need the platform user IDs of recently active traders.

**Instead:** Use [Get Users with Filters](https://docs.returning.ai/api-reference/users/get-users-with-filters.md) instead to find traders by email, custom field or other filters.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `None`

Send a Community API key as `Authorization: Bearer <API_KEY>`, and keep it on your server. This endpoint needs no specific permission, but `communityId` must be the community that owns your key.

## Behaviour

Traders are sorted online first, then by most recent sign-in, so the order shifts as traders come and go; don't rely on paging to visit every trader exactly once. Results are cached, so a trader who just joined, or a profile that just changed, may not show straight away. To check one trader, use Get User Data.

By default every trader includes all ten fields. Send one or more field flags, such as `email=true&id=true`, to get only those fields.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | Your community's ID. Use the community that owns your API key. (24 hex characters) |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Page number. (Min 1; default `1`) |
| `limit` | `integer` | No | Traders per page. (Default 20; max 100) |
| `_id` | `boolean` | No | Send `true` to include `_id`. Sending any field flag returns only the flagged fields. |
| `id` | `boolean` | No | Send `true` to include `id`, the platform user ID. |
| `avatar` | `boolean` | No | Send `true` to include `avatar`. |
| `displayName` | `boolean` | No | Send `true` to include `displayName`. |
| `username` | `boolean` | No | Send `true` to include `username`. |
| `firstName` | `boolean` | No | Send `true` to include `firstName`. |
| `lastName` | `boolean` | No | Send `true` to include `lastName`. |
| `email` | `boolean` | No | Send `true` to include `email`. |
| `isOnline` | `boolean` | No | Send `true` to include `isOnline`. |
| `lastLogin` | `boolean` | No | Send `true` to include `lastLogin`. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key. No specific permission is needed. (`Bearer <API_KEY>`) |

### Example request

```bash
curl --request GET \
  --url 'https://api.returning.ai/v1/communities/66f000000000000000000010/users?page=1&limit=20' \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

A `200` returns up to `limit` traders in `data`, with the page details in `meta`. A trader whose profile is missing a required value, such as an email, is left out of `data` and listed in `meta.validationErrors` instead.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | - |
| `meta.status` | `string` | always | - |
| `meta.statusCode` | `integer` | always | - |
| `meta.total` | `integer` | always | Number of community memberships. It can be higher than the traders you can page through. |
| `meta.page` | `integer` | always | The page returned. |
| `meta.limit` | `integer` | always | The page size used. |
| `meta.validationErrors` | `object[]` | - | Traders left out of this page because their profile is missing a required value, such as an email, with the reason. |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object[]` | always | Up to `limit` traders, online traders first, then by most recent sign-in. |
| `data._id` | `string` | by default | The trader's internal record ID. |
| `data.id` | `number` | by default | The trader's platform user ID, as a number here. Store it as a string. |
| `data.avatar` | `string` | by default | Avatar image URL, or `null`. (Nullable) |
| `data.displayName` | `string` | by default | Public display name. |
| `data.username` | `string` | by default | Username. |
| `data.firstName` | `string` | by default | First name, or `********` when the trader's privacy settings hide it. |
| `data.lastName` | `string` | by default | Last name, or `********` when hidden. |
| `data.email` | `string` | by default | Email, or `********` when hidden. |
| `data.isOnline` | `boolean` | by default | `true` while the trader is online. |
| `data.lastLogin` | `string` | by default | When the trader last signed in. (Date-time) |

### Example response (200)

```json
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "message": "Get community users success.",
  "data": [
    {
      "_id": "<userObjectId>",
      "id": 3247779,
      "avatar": null,
      "displayName": "Sample Trader",
      "username": "sample_trader",
      "firstName": "Sample",
      "lastName": "Trader",
      "email": "trader@example.com",
      "isOnline": false,
      "lastLogin": "2026-09-26T08:30:00.000Z"
    }
  ]
}
```

## Errors

Errors on this endpoint have no machine-readable code; branch on the HTTP status. Without an `Authorization` header the `401` body is not JSON. An unexpected failure returns `500`; retry it with backoff.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | `page` is below 1, `limit` is outside 1-100, either isn't a number, or `communityId` isn't a valid ID. `detail` names the parameter. |
| 401 | - | The key is missing, invalid or expired, or it can't access this community. Send `Authorization: Bearer <API_KEY>` with a current key for your own community. |

**Retries:** This endpoint is read-only, so retrying the exact same request is safe after a network error or a `500`. Use bounded exponential backoff. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get User Data](https://docs.returning.ai/api-reference/users/get-user-data.md): `POST /v1/users/info`. Read one trader in full, including roles, coins, XP and custom fields, with their `id`.
- [Search traders with Get Users with Filters](https://docs.returning.ai/api-reference/users/get-users-with-filters.md): `POST /v1/users/filter`.