Search user gamification logs
POST
/v1/gamifications/logs
What this endpoint does
INFO
user value is resolved only inside that community. Do not send a community ID.Quick start
Authentication and permission
Authorization header:getUserStats permission. Missing, invalid, expired, or under-permissioned keys currently return HTTP 401.Request body
user is required. Send a JSON body; there are no query or multipart parameters.| Field | Required | Meaning |
|---|---|---|
user | Yes | User email or Returning.AI client ID, as a non-empty string. Resolution is limited to the API key’s community. |
date | No | UTC calendar-date filter using gt, gte, lt, or lte with YYYY-MM-DD values. |
time | No | UTC time-of-day filter using gt, gte, lt, or lte with zero-padded HH:mm values. |
action | No | Array of exact action labels. A row matches when its action is in the array. |
limit | No | Rows per page. Defaults to 100; minimum 1, maximum 100. |
page | No | 1-based page number. Defaults to 1. |
Filter behavior
date.gte and date.lte include the named UTC calendar dates.date.gt and date.lt exclude the named UTC calendar dates.time comparisons use the event’s UTC HH:mm value.action values are combined with OR semantics.Success and pagination
200 returns status: "success", pagination under data.pagination, and event rows under data.data.hasNextPage or increment page until it becomes false. A valid search with no matching events is successful and returns data.data: [], total: 0, and totalPages: 0.Event fields
| Field | Meaning |
|---|---|
_id | Stable gamification-log identifier. Use it when deduplicating paginated exports. |
email | Resolved user email. Treat it as personal data. |
action | Human-readable event action when available. Older events may omit it. |
action_details | Additional event detail when available; otherwise null. |
xp | XP delta recorded by the event when available. Positive and negative values are possible. |
currency | Loyalty-coin delta recorded by the event. Positive and negative values are possible. |
date | Event date in UTC, formatted YYYY-MM-DD. |
time | Event time in UTC, formatted HH:mm. |
Errors and recovery
| HTTP | Meaning | What to do |
|---|---|---|
400 | Missing user, invalid pagination, or invalid request shape. | Correct the JSON body. Keep page >= 1 and 1 <= limit <= 100. |
401 | Missing, invalid, expired, or under-permissioned API key. | Replace or update the key and confirm getUserStats. Do not retry unchanged credentials. |
404 | The supplied user does not exist in the API key’s community. | Verify the email/client ID and that the key belongs to the intended community. |
500 | Unexpected service error. | Retry with bounded backoff; contact Returning.AI support if it persists. |
TIP
_id to deduplicate and do not treat page numbers as an immutable snapshot.Privacy
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://api.returning.ai/v1/gamifications/logs' \
--header 'Authorization: Bearer <COMMUNITY_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"user": "client@example.com",
"limit": 100,
"page": 1
}'Response Response Example
200 - Populated page
{
"status": "success",
"data": {
"pagination": {
"total": 3,
"currentPage": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
},
"data": [
{
"_id": "66c2f2a7b83b0b1234567890",
"email": "client@example.com",
"action": "Send message",
"action_details": "Posted a message in a community channel",
"xp": 20,
"currency": 5,
"date": "2026-08-17",
"time": "09:30"
}
]
}
}Modified at 2026-08-17 09:12:14