Returning.AIDevelopers
v1

API reference / User Fields / User Field History

.md

Get user field histories for a specific field

List every recorded change to one user field across all your traders, newest first, a page at a time.

Last updated 26 Sep 2026API v1

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

When to use this

  • Check which traders a feed updated for one field, such as every KYC status change today.
  • Audit a field before you change its type or delete it, to see how it's being written.
  • Follow XP or coin changes across your community by reading total_xp or total_coins.

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 any trader's value for the field adds one entry, and the newest entry comes first. Its storedValue is that trader's value after the change; for numerical fields it is the running total.

Entries are tied to the field's _id. Once you delete a field its history can't be read here, and a new field created with the same key starts with an empty history. The old entries still appear in Get all user field histories in a community.

For the built-in total_xp and total_coins fields, the list holds every trader's XP or coin changes instead. action uses the platform's own labels rather than overwrite, increase and decrease, and storedValue is usually null. Premium currency changes are not included in total_coins.

Request#

Path parameters#

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

Rule24 hex characters

Eg"66f000000000000000000010"

fieldIdOrName#stringREQUIRED
The field key, or the definition's _id. Capitals and spaces are cleaned up as on create, so KYCStatus finds kycstatus.

RuleField key or 24-character ID

Eg"kycstatus"

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/user-fields/kycstatus/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 field 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 field on this endpoint.
total#numberALWAYS
Entries for this field across all pages.

Eg2

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

data#object[]ALWAYS
This page of entries, newest first, across every trader. Empty when the field 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, or null when the entry doesn't hold one, which is usual for total_xp and total_coins.
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. 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": "field",
    "total": 2,
    "page": 1,
    "limit": 50,
    "hasNext": false
  },
  "message": "Read user field histories for specific 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. A 404 USER_FIELD_NOT_FOUND means the field doesn't exist now; it isn't an empty history.

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_FIELD_NOT_FOUNDFix the data
No field in your community has this key or ID, or the field was deleted. 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#

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