Returning.AIDevelopers
v1

API reference / Gamification / Streaks & Mini Games

.md

Get mini-game and streak state

Read one trader's spin-wheel and streak state right now, by email.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/mini-game-streak-stats
Permission
customerSuccess
Retries
Read-only; exact retries are safe

When to use this

  • A trader asks why they can't spin a wheel, and support needs their current spins.
  • Check whether a trader has cleared a wheel's mission or already spun today.
  • Show a trader's current streak counts in your own support tool.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
customerSuccessShown in the dashboard as “Customer Success”

Use a Community API key with customerSuccess, and keep it on your server. The key decides which community's wheels and streaks you read.

Behaviour#

This read is worked out fresh on every request and changes nothing: it doesn't use spins or touch streaks. Values can differ between two calls if a spin is earned, used or expires in between. spinToday uses the UTC day, not the trader's or your time zone. spins, missionCleared, spinToday and currentStreak are separate signals; one doesn't imply another.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with customerSuccess.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send the trader's email. The email lookup isn't limited to your community. An email that belongs to someone outside your community returns 200 with your wheels and streaks at zero or false, not 404. Confirm the trader with Get User Data first if that matters.

email#stringREQUIRED
The trader's email. Matched without regard to case.

RuleEmail format

Eg"trader@example.com"

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

Response#

A 200 returns data.wheels and data.streaks. Both can be empty when your community has no active wheels or streaks, and a trader can have every value at zero or false. That is a successful read, not an error. 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.

RuleUser mini game and streak stats fetched successfully

data#objectALWAYS
The trader's current state.

Eg{ ... }

wheels#object[]ALWAYS
One entry per active spin-the-wheel game in your community. Order isn't fixed; match by name.

Eg[ ... ]

name#stringALWAYS
The wheel's name as set up in your community. Names can change, so don't store them as IDs.

Eg"Daily Spin the Wheel"

spins#integerALWAYS
Spins the trader has available now.

RuleMin 0

Eg1

missionCleared#booleanALWAYS
true when the trader has completed the wheel's mission for the current period.

Egtrue

spinToday#booleanALWAYS
true when the trader has spun this wheel today, in UTC.

Egfalse

currentStreak#numberALWAYS
The trader's current streak on this wheel. 0 when they have none.

RuleMin 0

Eg3

streaks#object[]ALWAYS
One entry per streak set up in your community. Order isn't fixed; match by name.

Eg[ ... ]

name#stringALWAYS
The streak's name as set up in your community.

Eg"Login Streak"

currentStreak#numberALWAYS
The trader's current count for this streak. 0 when they have none.

RuleMin 0

Eg5

missionCleared#booleanALWAYS
true when the trader has completed the streak's current, unexpired mission.

Egtrue

{
  "status": "success",
  "message": "User mini game and streak stats fetched successfully",
  "data": {
    "wheels": [
      {
        "name": "Daily Spin the Wheel",
        "spins": 1,
        "missionCleared": true,
        "spinToday": false,
        "currentStreak": 3
      }
    ],
    "streaks": [
      {
        "name": "Login Streak",
        "currentStreak": 5,
        "missionCleared": true
      }
    ]
  }
}

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 400 has detail.email explaining the problem, and 404 means no account uses that email.

Fix the request03

400Fix the request
email is missing or isn't a valid email. detail.email says which. Correct it and send again.
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 customerSuccess, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys.

Fix the data02

404Fix the data
No account uses this email. Check the email, or look the trader up with Get User Data.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff02

500Retry with backoff
The state could not be read. Retry the same request with exponential backoff.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing was read.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Get user mini game and streak stats endpoint validation error.",
  "detail": {
    "email": "Invalid email format"
  },
  "solution": "Check your body in request and try again"
}

Next step#

Get User DataPOST/v1/users/infoConfirm the trader belongs to your community, since this lookup is by email only.