Returning.AIDevelopers
v1

API reference / Community / Community Users

.md

Get user

Get one trader's name, username, email, avatar, online status and last sign-in, by their internal record ID or email.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/communities/{communityId}/users/{userId}
Permission
None
Retries
Read-only; exact retries are safe

When to use this

  • You have a trader's internal record ID or email and want their public profile for your own tools.
  • You want to know whether a trader is online right now, or when they last signed in.
  • You want only a few profile fields, such as the email and platform user ID.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
NoneAny Community API key for this community works

Send a Community API key as Authorization: Bearer <API_KEY>, and keep it on your server. No specific permission is needed, so any key for your community works. communityId in the path must be the community that owns your key; another community's ID returns 401.

Behaviour#

userId is matched as an internal record ID when it looks like one, and as an email otherwise. Email matching ignores case. Usernames and platform user IDs don't match, so they return 404.

A deleted trader is still returned here. Get User Data returns 404 for the same trader, so use it when you need to know whether an account is still active. Profile changes can take a short time to show.

Any query parameter switches the response to field selection: only the fields you set to true come back. A parameter that isn't a field name, such as page=1, or a field set to false, returns 200 with an empty data object. To get every field, send no query string.

Request#

Path parameters#

communityId#stringREQUIRED
Your community's ID. Use the community that owns your API key.

Rule24 hex characters

Eg"66f000000000000000000010"

userId#stringREQUIRED
The trader's internal record ID (_id), or their email. A platform user ID or a username returns 404.

RuleRecord ID or email

Eg"<userObjectId>"

Query parameters#

_id#booleanOPTIONAL
Send true to include _id. Sending any query parameter returns only the fields set to true.

Egtrue

id#booleanOPTIONAL
Send true to include id, the platform user ID.

Egtrue

avatar#booleanOPTIONAL
Send true to include avatar.

Egtrue

displayName#booleanOPTIONAL
Send true to include displayName.

Egtrue

username#booleanOPTIONAL
Send true to include username.

Egtrue

firstName#booleanOPTIONAL
Send true to include firstName.

Egtrue

lastName#booleanOPTIONAL
Send true to include lastName.

Egtrue

email#booleanOPTIONAL
Send true to include email.

Egtrue

isOnline#booleanOPTIONAL
Send true to include isOnline.

Egtrue

lastLogin#booleanOPTIONAL
Send true to include lastLogin.

Egtrue

Headers#

Authorization#stringREQUIRED
Community API key. No specific permission is needed.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/communities/66f000000000000000000010/users/<userObjectId>' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns one trader in data, not a list. meta has only status and statusCode.

meta#objectALWAYS

Eg{"status": "success", "statusCode": 200}

status#stringALWAYS

Eg"success"

statusCode#integerALWAYS

Eg200

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Get user success."

data#objectALWAYS
The trader. Without query parameters it has all ten fields; with them, only the fields set to true.

Eg{ ... }

_id#string
The trader's internal record ID.

Eg"<userObjectId>"

id#number
The trader's platform user ID, as a number here. Store it as a string.

Eg3247779

avatar#string
Avatar image URL, or null.

RuleNullable

Egnull

displayName#string
Public display name.

Eg"Sample Trader"

username#string
Username.

Eg"sample_trader"

firstName#string
First name, or ******** when the trader's privacy settings hide it.

Eg"Sample"

lastName#string
Last name, or ******** when hidden.

Eg"Trader"

email#string
Email, or ******** when hidden.

Eg"trader@example.com"

isOnline#boolean
true while the trader is online.

Egfalse

lastLogin#string
When the trader last signed in.

RuleDate-time

Eg"2026-09-26T08:30:00.000Z"

{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Get user 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 and read detail. Without an Authorization header the 401 body is not JSON.

Fix the request02

400Fix the request
communityId isn't a 24-character hex ID. detail.communityId says Community ID is required even when you sent a value.
401Fix the request
The key is missing or invalid (Token is wrong.), or communityId isn't the community that owns your key (User can only get your own information!). Send a current key and your own community's ID.

Fix the data01

404Fix the data
No trader matches userId. Send the internal record ID or the email; for a platform user ID, use Get User Data.

Retry with backoff01

500Retry with backoff
The read failed unexpectedly. Retry the same request with exponential backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Get user validation error.",
  "detail": {
    "communityId": "Community ID is required"
  },
  "solution": "Check your params in request and try again"
}

Next step#

Get User DataPOST/v1/users/infoRead the same trader in full, including roles, XP, coins and custom fields, and check that the account is still active.