Get all user field histories in a community
GET
/v1/communities/{communityId}/user-field-histories
What this endpoint does
INFO
GET /v1/communities/{communityId}/user-field-histories?page=1&limit=50 → paginate while meta.hasNext is true → narrow with the user or field history URLs.Quick start
communityId is the 24-character community ObjectId that belongs to this API key. Send page and limit.Authentication and permission
Authorization: Bearer <COMMUNITY_API_KEY> with userFields. A key from another community returns 403 API_KEY_COMMUNITY_MISMATCH.Complete examples
page=1&limit=5 on Codex returned meta.code: USER_FIELD_HISTORIES_LISTED, message: Read all user field histories api success., meta.total: 95, meta.hasNext: true, and five rows.403 API_KEY_COMMUNITY_MISMATCH The authenticated API key cannot access the requested community._id, communityID, userID, userObjectID, userNumericID, fieldID, fieldName, fieldType, value, storedValue, action, createdAt, updatedAt.value / storedValue as synthetic in public examples.Success and readback
200. Envelope is { meta, message, data }. data is an array. meta includes status, statusCode, code: USER_FIELD_HISTORIES_LISTED, scope: community, total, page, limit, and hasNext.CHECK
200 with rows means canonical history reads are enabled for this community. An empty data array with total: 0 means no history in this window, not that the route is off.Errors and recovery
| Status | When | Recovery |
|---|---|---|
403 API_KEY_COMMUNITY_MISMATCH | communityId is not the key's community | Use the ObjectId from the key's community. |
401 | Missing or invalid key | Replace the community key. |
400 | Invalid page / limit | Use positive integers; keep limit small. |
503 USER_FIELD_HISTORY_READ_NOT_READY was not returned on 2026-08-19 Codex. Do not document that code as current for api.returning.ai unless a later probe sees it.Retry safety
TIP
500 with bounded backoff. Do not retry 403 without changing communityId.Gotchas
https://api.returning.ai as of 2026-08-19. Older internal notes that said it was default-off / 503 are stale for this gateway.userID and userObjectID both appear. Use userObjectID when calling user-scoped history.value and storedValue can match for overwrite actions.Next steps
Request
Path Params
Query Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://adss-application.returning.ai/v1/communities/507f1f77bcf86cd799439011/user-field-histories?page=1&limit=10'Response Response Example
200 - Success
{
"meta": {
"status": "success",
"statusCode": 200,
"total": 125,
"page": 1,
"limit": 10
},
"message": "Get user field histories",
"data": [
{
"_id": "685a48f5cbfa3985ad581bae",
"field": {
"_id": "6857de260f3c24d98fd7ca89",
"field": "hello",
"name": "Hello",
"type": "numerical",
"isCustom": true,
"createdAt": "2025-06-22T10:42:32.844Z",
"updatedAt": "2025-06-22T10:42:32.844Z"
},
"user": {
"_id": "61100af5c548eb5c7ebc7819",
"id": 1,
"avatar": "https://returning.ai/admin.png",
"displayName": "Admin",
"username": "admin"
},
"value": 500,
"action": "overwrite",
"createdAt": "2025-06-24T06:43:01.078Z"
},
{
"_id": "685957701ff244c62bd2e5b5",
"field": {
"_id": "6857de260f3c24d98fd7ca90",
"field": "xp",
"name": "Experience Points",
"type": "number",
"isCustom": true,
"createdAt": "2025-06-20T11:20:45.000Z",
"updatedAt": "2025-06-20T11:20:45.000Z"
},
"user": {
"_id": "507f1f77bcf86cd799439013",
"id": 12346,
"avatar": null,
"displayName": "Jane Smith",
"username": "janesmith"
},
"value": 50,
"action": "increase",
"createdAt": "2025-06-23T13:30:15.123Z"
}
]
}Modified at 2026-08-18 17:20:43