Get community users

What this endpoint does

Returns a page of members for one community. Use it when you already have that community's ObjectId and need a directory snapshot for an admin or member view.

It does not search by email, username, or custom field. It does not return roles, XP, coins, or custom-field values.

INFO

Workflow

Authenticate for this community → GET with no query string → read data and meta.total → look up one member or search with a different endpoint.

Quick start

Replace <communityId> with a 24-character community ObjectId. On the current public runtime, omit query parameters when you need rows returned.

Authentication and permission

Send a Bearer credential for the target community:

a community API key that belongs to that community, or

a member session token with COMMUNITY_MEMBER, COMMUNITY_ADMIN, or COMMUNITY_OWNER on that community.

The permission check uses the authenticated principal's community membership. It runs after ObjectId validation and before the service loads members.

Failure	Observed result	Recovery
Missing `Authorization`	`401` from the authorization middleware. The body may be MessagePack with `Content-Type: text/html` rather than JSON.	Add `Authorization: Bearer <token>`.
Invalid token	`401` JSON `Authorization middleware error.` with `detail: Token is wrong.`	Replace the token.
Valid token, wrong community	`401` `You are not allowed to get users`	Use a credential that belongs to this community.

Complete examples

The structured 200 populated example is the current no-query success shape. The structured 200 empty example is the current response when page, limit, or field-select query flags are sent: meta.total stays populated and data is [].

Treat names, avatars, and timestamps in examples as synthetic.

Success and readback

HTTP 200. message is Get community users success. The envelope is { meta, message, data }.

data is an array of user objects.

meta.total is the community membership-array length.

meta.page defaults to 1.

meta.limit defaults to 20 and cannot exceed 100.

Default fields are _id, id, avatar, displayName, username, firstName, lastName, email, isOnline, and lastLogin. Rows are ordered online first, then by lastLogin descending.

This is a read. Repeat the same request to refresh. There is no extra readback call.

CHECK

Default page

Call the path with no query string. The current https://api.returning.ai runtime returns up to 20 members and the full default field set.

Errors and recovery

Status	When	Recovery
`400` `Get users validation error.` `detail.communityId: Community ID is required`	`communityId` is missing or not an ObjectId	Send a 24-character ObjectId.
`400` `Get community users error.` `detail.page: Page must be at least 1`	`page=0`	Use `page` ≥ 1 after query parameters start returning rows.
`400` `Get community users error.` `detail.limit: Limit cannot exceed 100`	`limit=101`	Use `limit` 1–100 after query parameters start returning rows.
`401` authorization middleware / `Token is wrong.`	Missing or invalid Bearer token	Add a valid community key or member token.
`401` `You are not allowed to get users`	Token is valid but cannot access this community	Switch to a credential for this community.

A 500 from the service is an unexpected failure. Retry with bounded backoff and stop if it persists. This run did not induce 500.

Retry safety

TIP

Exact retry

This GET does not create or modify users. Retry timeouts and 500 with bounded exponential backoff. Do not retry 400 or 401 without changing the path, query, or credential.

The service caches community membership and the aggregation pipeline. A retry immediately after a membership change can return a stale page.

Gotchas

Query parameters currently return no rows

avatar may be null.

Privacy settings can replace firstName, lastName, or email with ********.

meta.total can be larger than data.length.

Users that fail response validation are omitted from data and may appear in meta.validationErrors.

Do not send a request body on this GET.

A malformed community path such as /v1/communities/users is a different route and is not this operation.

Next steps

Search members by email or field

Use POST /v1/users/filter when you need filters. Send a required fields array. This list endpoint does not search.

curl --location 'https://adss-application.returning.ai/v1/communities/61100af5c548eb5c7ebc7819/users?page=1&limit=20&_id=true&id=true&avatar=true&displayName=true&username=true&firstName=true&lastName=true&email=true&isOnline=true&lastLogin=true' \ --header 'Authorization: Bearer <COMMUNITY_API_KEY>'

{ "meta": { "status": "success", "statusCode": 200, "total": 58, "page": 1, "limit": 20 }, "message": "Get community users success.", "data": [ { "_id": "61100af5c548eb5c7ebc7819", "id": 11898, "avatar": "https://example.com/avatar.png", "displayName": "Alex Admin", "username": "alex.admin", "firstName": "Alex", "lastName": "Admin", "email": "alex.admin@example.com", "isOnline": true, "lastLogin": "2026-08-17T20:45:33.832Z" }, { "_id": "61100af5c548eb5c7ebc781a", "id": 11899, "avatar": null, "displayName": "Jordan Member", "username": "jordan.member", "firstName": "Jordan", "lastName": "Member", "email": "jordan.member@example.com", "isOnline": false, "lastLogin": "2026-08-16T14:01:15.111Z" } ] }

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

Get community users

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps