# Get mini-game and streak state Read one trader's spin-wheel and streak state right now, by email. - Endpoint: `POST https://api.returning.ai/v1/users/mini-game-streak-stats` - Section: Gamification / Streaks and mini games - Authentication: `Authorization: Bearer ` (Community API key) - Permission: `customerSuccess` (Shown in the dashboard as "Customer Success") - Retries: Read-only; exact retries are safe - Guide: hand-written - Verified: live, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/get-mini-game-and-streak-state ## 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. **Instead:** Use [List user streak logs](https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/list-user-streak-logs.md) instead to see how a trader's streaks changed over time. ## Authentication - Header: `Authorization: Bearer ` - Permission: `customerSuccess` 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 | Name | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | Yes | Community API key with `customerSuccess`. (`Bearer `) | | `Content-Type` | `string` | Yes | Request body format. (`application/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. | Name | Type | Required | Description | | --- | --- | --- | --- | | `email` | `string` | Yes | The trader's email. Matched without regard to case. (Email format) | ### Example request ```bash curl --request POST \ --url https://api.returning.ai/v1/users/mini-game-streak-stats \ --header 'Authorization: Bearer ' \ --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. ### Response fields | Field | Type | Presence | Description | | --- | --- | --- | --- | | `status` | `string` | always | Result of the request. (`success`) | | `message` | `string` | always | Human-readable summary. Do not branch on it. (`User mini game and streak stats fetched successfully`) | | `data` | `object` | always | The trader's current state. | | `data.wheels` | `object[]` | always | One entry per active spin-the-wheel game in your community. Order isn't fixed; match by `name`. | | `data.wheels.name` | `string` | always | The wheel's name as set up in your community. Names can change, so don't store them as IDs. | | `data.wheels.spins` | `integer` | always | Spins the trader has available now. (Min 0) | | `data.wheels.missionCleared` | `boolean` | always | `true` when the trader has completed the wheel's mission for the current period. | | `data.wheels.spinToday` | `boolean` | always | `true` when the trader has spun this wheel today, in UTC. | | `data.wheels.currentStreak` | `number` | always | The trader's current streak on this wheel. `0` when they have none. (Min 0) | | `data.streaks` | `object[]` | always | One entry per streak set up in your community. Order isn't fixed; match by `name`. | | `data.streaks.name` | `string` | always | The streak's name as set up in your community. | | `data.streaks.currentStreak` | `number` | always | The trader's current count for this streak. `0` when they have none. (Min 0) | | `data.streaks.missionCleared` | `boolean` | always | `true` when the trader has completed the streak's current, unexpired mission. | ### Example response (200) ```json { "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 request | Status | Code | What to do | | --- | --- | --- | | 400 | - | `email` is missing or isn't a valid email. `detail.email` says which. Correct it and send again. | | 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer ` with a current Community API key. | | 403 | `API_KEY_PERMISSION_DENIED` | 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 data | Status | Code | What to do | | --- | --- | --- | | 404 | - | No account uses this email. Check the email, or look the trader up with Get User Data. | | 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. | ### Retry with backoff | Status | Code | What to do | | --- | --- | --- | | 500 | - | The state could not be read. Retry the same request with exponential backoff. | | 500 | `AUTHENTICATION_FAILED` | The key could not be checked. Retry with backoff; nothing was read. | **Retries:** This endpoint is read-only and doesn't accept an `Idempotency-Key`. Retrying the exact same request is safe after a network error or a 5xx; use bounded exponential backoff. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry. ## Next step - [Get User Data](https://docs.returning.ai/api-reference/users/get-user-data.md): `POST /v1/users/info`. Confirm the trader belongs to your community, since this lookup is by email only. - [See how their streaks changed with List user streak logs](https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/list-user-streak-logs.md): `GET /v1/streak-logs`.