API reference / User Fields / User Field History

Get user field histories for a specific user

List every recorded change to one trader's user field values, XP and coins, newest first, a page at a time.

Last updated 26 Sep 2026API v1

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

When to use this

Support asks why a trader's value, XP or coin balance changed, and you need the full timeline.
Check everything your platform wrote for one trader after an onboarding or sync.
Reconcile one trader's record between your systems and Returning.AI.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: userFieldsShown in the dashboard as “User Fields”

Use a Community API key with the userFields permission, and keep it on your server. communityId must be the ID of the community that owns the key.

Behaviour#

The list holds the trader's changes to every field, newest first, so data[0] is the latest change. It includes:

Changes to your custom fields. Creating the trader with a broker identifier adds an entry for the identifier field.
XP and coin changes, as entries for the built-in total_xp and total_coins fields. Their action uses the platform's own labels rather than overwrite, increase and decrease, and storedValue is usually null. Premium currency changes are not included.

Entries for a field you've deleted stay in the list, with fieldType set to null. Once you delete the trader, their history can't be read.

Request#

Path parameters#

communityId#stringREQUIRED

Your community's ID. It must be the community that owns your API key.

Rule24 hex characters

Eg"66f000000000000000000010"

userId#stringREQUIRED

The trader. Use the platform user ID, or their internal record ID, email or username. URL-encode an email.

RulePlatform user ID recommended

Eg"3247779"

Query parameters#

page#integerOPTIONAL

The page to return, starting at 1.

RuleWhole number from 1; default 1

Eg1

limit#integerOPTIONAL

Entries per page, from 1. page × limit can't be more than 10,000.

RuleDefault 50; max 100

Eg50

Headers#

Authorization#stringREQUIRED

Community API key with userFields.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/communities/66f000000000000000000010/users/3247779/user-field-histories?page=1&limit=50' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns one page of entries in data. Branch on the HTTP status and meta.code, never on message. To read everything, start at page=1 and ask for the next page while meta.hasNext is true. Only the first 10,000 entries can be paged to. A trader with no changes returns 200 with an empty list, not 404.

meta#objectALWAYS

Result details and paging.

Eg{ ... }

status#stringALWAYS

success.

Eg"success"

statusCode#numberALWAYS

200.

Eg200

code#stringALWAYS

Machine-readable result code.

RuleUSER_FIELD_HISTORIES_LISTED

scope#stringALWAYS

Always user on this endpoint.

total#numberALWAYS

Entries for this trader across all pages.

Eg3

page#numberALWAYS

The page returned.

Eg1

limit#numberALWAYS

The page size used.

Eg50

hasNext#booleanALWAYS

true when there are more entries after this page. Ask for page + 1.

message#stringALWAYS

Human-readable summary. Do not branch on it.

Eg"Read user field histories for specific user api success."

data#object[]ALWAYS

This page of entries, newest first, across every field. Empty when the trader has no changes, or past the last page.

Eg[ ... ]

_id#stringALWAYS

ID of the history entry.

Eg"66f000000000000000000511"

communityID#stringALWAYS

Your community ID.

userID#stringALWAYS

The trader's internal record ID. For total_xp and total_coins, their platform user ID as a number instead; use userNumericID to be safe.

userObjectID#stringALWAYS

The trader's internal record ID.

userNumericID#integerALWAYS

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

fieldID#stringALWAYS

The field definition's _id.

fieldName#stringALWAYS

The field key, such as kycstatus or total_xp.

fieldType#stringALWAYS

The field's current type. null when the field has since been deleted.

value#anyALWAYS

The value written, or for increase and decrease the amount. For total_xp and total_coins, the signed change, such as -25.

Eg"verified"

storedValue#anyALWAYS

The trader's value after this change. For numerical fields, the new total. null when no value after the change was recorded, which is usual for total_xp and total_coins.

action#stringALWAYS

overwrite, increase or decrease. For total_xp and total_coins, the platform's own label for the change instead, such as adjust xps,api or add,api.

Eg"overwrite"

createdAt#stringALWAYS

When the change was recorded.

RuleDate-time

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

updatedAt#stringALWAYS

When the entry last changed.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELD_HISTORIES_LISTED",
    "scope": "user",
    "total": 3,
    "page": 1,
    "limit": 50,
    "hasNext": false
  },
  "message": "Read user field histories for specific user api success.",
  "data": [
    {
      "_id": "66f000000000000000000511",
      "communityID": "66f000000000000000000010",
      "userID": "<userObjectId>",
      "userObjectID": "<userObjectId>",
      "userNumericID": 3247779,
      "fieldID": "66f000000000000000000510",
      "fieldName": "kycstatus",
      "fieldType": "single-line-text",
      "value": "verified",
      "storedValue": "verified",
      "action": "overwrite",
      "createdAt": "2026-09-26T08:30:00.000Z",
      "updatedAt": "2026-09-26T08:30:00.000Z"
    },
    {
      "_id": "66f000000000000000000601",
      "communityID": "66f000000000000000000010",
      "userID": 3247779,
      "userObjectID": "<userObjectId>",
      "userNumericID": 3247779,
      "fieldID": "66f000000000000000000602",
      "fieldName": "total_coins",
      "fieldType": "numerical",
      "value": -25,
      "storedValue": null,
      "action": "subtract,api",
      "createdAt": "2026-09-26T07:10:00.000Z",
      "updatedAt": "2026-09-26T07:10:00.000Z"
    },
    {
      "_id": "66f000000000000000000512",
      "communityID": "66f000000000000000000010",
      "userID": "<userObjectId>",
      "userObjectID": "<userObjectId>",
      "userNumericID": 3247779,
      "fieldID": "66f000000000000000000510",
      "fieldName": "kycstatus",
      "fieldType": "single-line-text",
      "value": "pending",
      "storedValue": "pending",
      "action": "overwrite",
      "createdAt": "2026-09-20T10:05:00.000Z",
      "updatedAt": "2026-09-20T10:05:00.000Z"
    }
  ]
}

Errors#

Every error carries its code in meta.code.

Fix the request04

400INVALID_PAGINATIONFix the request

page or limit isn't a whole number from 1, limit is over 100, or page × limit is over 10,000. detail names the limit and 10,000 rules; a bad page only says Invalid input.

401AUTHENTICATION_REQUIREDFix the request

The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.

403API_KEY_PERMISSION_DENIEDFix the request

The key lacks userFields. Add the permission in Settings > Integration > API Keys.

403API_KEY_COMMUNITY_MISMATCHFix the request

communityId is not the community that owns your key, or isn't a valid ID. Use your own community's ID.

Fix the data02

404USER_NOT_FOUNDFix the data

No active trader in your community matches userId. A trader who isn't a member, or whom you deleted, returns this too. A 12-character username or email can't be matched, so use the platform user ID. meta.userIdentifier echoes what you sent.

404COMMUNITY_NOT_FOUNDFix the data

The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff01

500USER_FIELD_OPERATION_FAILEDRetry with backoff

The history could not be read. Retry the same request with exponential backoff.

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "INVALID_PAGINATION"
  },
  "message": "Read user field histories api validation error.",
  "detail": "Limit must be at most 100",
  "solution": "Use integer pagination within the supported window."
}

Next step#

Get a trader's field historyGET/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/historiesNarrow to one field for this trader.

Compare with current values in Get User Data

Get user field histories for a specific user

When to use this

01Authentication#

02Behaviour#

03Request#