Returning.AIDevelopers
v1

API reference / User Fields / User Field History

.md

Get a trader's field history

List every recorded change to one trader's value for one user field, 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-fields/{fieldIdOrName}/histories
Permission
userFields
Retries
Read-only; exact retries are safe

When to use this

  • Confirm that a value you wrote with Update a user field value was saved, and what the trader's value is now.
  • A write timed out or returned an unclear result, and you need to know whether it was applied before you send it again.
  • Audit how a trader's value for a field changed over time, such as when their KYC status moved to verified.

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#

Each change to the trader's value adds one entry, and the newest entry comes first, so data[0] is the latest change. Its storedValue is the trader's value after that change; for numerical fields it is the running total.

Entries are tied to the field's _id. If you delete a field and create a new one with the same key, the old field's entries don't appear here.

For the built-in total_xp and total_coins fields, the list holds the trader's XP or coin changes instead, and action uses the platform's own labels rather than overwrite, increase and decrease.

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"

fieldIdOrName#stringREQUIRED
The field key, or the definition's _id. Not the display name.

RuleField key or 24-character ID

Eg"kycstatus"

Query parameters#

page#integerOPTIONAL
Optional. The page to return, starting at 1.

RuleWhole number from 1; default 1

Eg1

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

RuleDefault 50; max 100

Eg20

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-fields/kycstatus/histories?page=1&limit=20' \
  --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 for the field 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_field on this endpoint.
total#numberALWAYS
Entries for this trader and field across all pages.

Eg2

page#numberALWAYS
The page returned.

Eg1

limit#numberALWAYS
The page size used.

Eg20

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 and user field api success."

data#object[]ALWAYS
This page of entries, newest first. Empty when the trader has no changes for this field, 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 instead; use userNumericID to be safe.
userObjectID#stringALWAYS
The trader's internal record ID, or null when the entry doesn't hold one.
userNumericID#integerALWAYS
The trader's platform user ID, as a number here. Store it as a string.
fieldID#stringALWAYS
The definition's _id.
fieldName#stringALWAYS
The field key.
fieldType#stringALWAYS
The field's current type, even if the entry was written under an earlier one.
value#anyALWAYS
The value written, or for increase and decrease the amount.

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.
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 or edit.

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_field",
    "total": 2,
    "page": 1,
    "limit": 20,
    "hasNext": false
  },
  "message": "Read user field histories for specific user and user field 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": "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. The trader is looked up before the field, so if both are wrong you get USER_NOT_FOUND.

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. Use your own community's ID.

Fix the data03

404USER_NOT_FOUNDFix the data
No active trader in your community matches userId; a trader who isn't a member 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.
404USER_FIELD_NOT_FOUNDFix the data
No field in your community has this key or ID. Check the key with List user field definitions. meta.fieldIdOrName 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#

Update a user field valuePOST/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/historiesWrite the trader's next value, then read the history again to confirm it.