API reference / User Fields / User Field History

Get all user field histories in a community

List every recorded change to any trader's user field values in your community, newest first, a page at a time.

Last updated 26 Sep 2026API v1

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

When to use this

Reconcile the values your platform wrote in a time window against what Returning.AI recorded.
Investigate an incident, such as a feed that wrote the wrong value, when you don't yet know which traders or fields it touched.
Export the recent change log to your own reporting store.

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 every trader's changes to every field in your community, newest first, so data[0] is the latest change. It includes:

Changes to your custom fields, such as those made with Update a user field value. Creating a trader with a broker identifier also 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 stay after you delete a field. They keep their fieldName and fieldID, and fieldType becomes null.

Request#

Path parameters#

communityId#stringREQUIRED

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

Rule24 hex characters

Eg"66f000000000000000000010"

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-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, so for a longer export narrow the read by trader or field. A community with no changes returns 200 with an empty list.

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 community on this endpoint.

total#numberALWAYS

Entries in your community across all pages.

Eg1551

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

data#object[]ALWAYS

This page of entries, newest first, across every trader and field. Empty 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 field definition's _id.

fieldName#stringALWAYS

The field key, such as kycstatus or total_coins.

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 add,api or redeem reward,<product name>.

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": "community",
    "total": 1551,
    "page": 1,
    "limit": 50,
    "hasNext": true
  },
  "message": "Read all user field histories 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": null,
      "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"
    }
  ]
}

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 data01

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 user field histories for a specific userGET/v1/communities/{communityId}/users/{userId}/user-field-historiesNarrow to one trader once you know who was affected.

Or narrow to one field with Get user field histories for a specific field

Get all user field histories in a community

When to use this

01Authentication#

02Behaviour#

03Request#