Returning.AIDevelopers
v1

API reference / Gamification

.md

Get user activity stats

Count one trader's messages, replies, reactions and social actions per day over the last 1 to 90 days.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/activity/stats
Permission
getUserStats
Retries
Read-only; exact retries are safe

When to use this

  • Show a trader how active they have been this month in your own app.
  • Check whether a trader met an activity target, such as 10 messages in a week.
  • Spot traders whose activity has dropped off, for a re-engagement campaign.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getUserStatsShown in the dashboard as “Get User Stats”

Use a Community API key with getUserStats, shown in the dashboard as Get User Stats, and keep it on your server. The key decides the community: the trader must be a member of it, and only activity in it is counted.

Behaviour#

This read changes nothing. Counts come from the trader's XP and coin history in your community. Each recorded message, reply, reaction or social action counts once. An entry that took XP or coins away, such as for a deleted message, counts as minus one, so a day's figure is net and can be 0 even after activity.

Days run from 00:00 to 23:59 UTC. The range always ends today, so days: 7 covers today and the six days before it.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with getUserStats.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send identifier and identifier_type. days is optional and must be a JSON number. An email with a space where a + should be is read as if it had the +.

identifier#stringREQUIRED
The trader's email or platform user ID. Emails ignore case.

RuleEmail or platform user ID

Eg"trader@example.com"

identifier_type#stringREQUIRED
What identifier is: email or userId (platform user ID). userID is rejected.

Ruleemail or userId

Eg"email"

days#integerOPTIONAL
How many days to count, ending today (UTC).

RuleJSON number, 1-90; default 30

Eg7

curl --request POST \
  --url https://api.returning.ai/v1/users/activity/stats \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "identifier": "trader@example.com",
    "identifier_type": "email",
    "days": 7
  }'

Response#

A 200 returns totals for the range in data.totals and one entry per day in data.daily_stats, newest first. A trader with no activity gets 0 everywhere: that is a real result, not a missing trader. This endpoint has no top-level code; branch on the HTTP status.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"User gamification stats fetched successfully"

data#objectALWAYS
The trader's activity.

Eg{ ... }

user_id#stringALWAYS
The trader's platform user ID, as a string.

Eg"3247779"

range#objectALWAYS
The days counted.

Eg{"start_date": "2026-09-25", "end_date": "2026-09-27"}

start_date#stringALWAYS
First day counted, as YYYY-MM-DD.

Eg"2026-09-25"

end_date#stringALWAYS
Last day counted, today, as YYYY-MM-DD.

Eg"2026-09-27"

totals#objectALWAYS
Totals across the range.

Eg{"messages": 5, "replies": 2, "reaction": 3, "socials": 0}

messages#integerALWAYS
Messages posted.

Eg5

replies#integerALWAYS
Replies posted, including replies to a mention.

Eg2

reaction#integerALWAYS
Reactions added. The field name is singular.

Eg3

socials#integerALWAYS
Social media actions the trader was rewarded for.

Eg0

daily_stats#object[]ALWAYS
One entry per day in the range, newest first. Days with no activity show 0.

Eg[ ... ]

date#stringALWAYS
The day, as YYYY-MM-DD in UTC.

Eg"2026-09-27"

messages#integerALWAYS
Messages posted that day.

Eg1

replies#integerALWAYS
Replies posted that day.

Eg0

reaction#integerALWAYS
Reactions added that day.

Eg2

socials#integerALWAYS
Social actions that day.

Eg0

{
  "status": "success",
  "message": "User gamification stats fetched successfully",
  "data": {
    "user_id": "3247779",
    "range": {
      "start_date": "2026-09-25",
      "end_date": "2026-09-27"
    },
    "totals": {
      "messages": 5,
      "replies": 2,
      "reaction": 3,
      "socials": 0
    },
    "daily_stats": [
      {
        "date": "2026-09-27",
        "messages": 1,
        "replies": 0,
        "reaction": 2,
        "socials": 0
      },
      {
        "date": "2026-09-26",
        "messages": 4,
        "replies": 2,
        "reaction": 1,
        "socials": 0
      },
      {
        "date": "2026-09-25",
        "messages": 0,
        "replies": 0,
        "reaction": 0,
        "socials": 0
      }
    ]
  }
}

Errors#

401 and 403 responses, and the authentication errors 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED, carry the code in meta.code. Other errors have no code. A trader who can't be found returns 500, not 404, with the reason in detail.

Fix the request03

400Fix the request
A field is missing or invalid: no identifier, identifier_type isn't email or userId, or days is sent as a string. detail names each field. days below 1 or above 90 returns 400 with message Days cannot be less than 1 or greater than 90 and no detail.
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 getUserStats, or it is a personal key. Use a Community API key and add Get User Stats in Settings > Integration > API Keys.

Fix the data02

500Fix the data
detail says why. User not found: no account matches the identifier. User not found in community: the trader isn't a member of your community. Check the identifier, or look the trader up with Get User Data. Any other detail means the counts could not be read; retry with exponential backoff.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff01

500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing was read.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Get user activity stats endpoint validation error.",
  "detail": {
    "identifier_type": "Invalid enum value. Expected 'userId' | 'email', received 'userID'"
  },
  "solution": "Check your body in request and try again"
}

Next step#

Get daily user XP and coin changesPOST/v1/users/activity/dailySee the XP and coins the same trader earned on a given day.