Returning.AIDocs
v1

API reference / Gamification

.md

Get tier configuration

Read your community's tiers and the XP each level in them needs.

Last updated 28 Oct 2026API v1

Method
GET
Path
https://api.returning.ai/v1/xp-settings/tiers-info
Permission
getTiersInfo
Retries
Read-only; exact retries are safe

When to use this

  • Show traders how far they are from the next level or tier, next to the XP you read with Get User Data.
  • Check tier and level names after an admin changes them.
  • Map level names to XP thresholds in your own reports.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getTiersInfoShown in the dashboard as “Get Tier Infos”

Use a Community API key with getTiersInfo, shown in the dashboard as Get Tier Infos, and keep it on your server. Unlike most endpoints, this one also needs your community's ID in communityId; send the community that owns your key.

Behaviour#

This read changes nothing. Tier and level names are whatever your admins set, and they can change, so don't store them as IDs. If two levels in a tier share a name, only the last one appears. The XP value is text with the unit on the end, such as 500 XP, so strip the unit before you compare it with a trader's XP.

This endpoint returns level-based tiers only. If your community's tiers use Value Range, where each tier starts at a minimum value and has no levels, those tiers aren't returned: data still shows the level-based tiers saved before the switch, or {} if there were none. Level-based tiers are also returned when tiers are switched off in the dashboard.

Request#

Query parameters#

communityId#stringREQUIRED
Your community's ID. Send the community that owns your API key.

Rule24-character hex ID

Eg66f000000000000000000010

Headers#

Authorization#stringREQUIRED
Community API key with getTiersInfo.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/xp-settings/tiers-info?communityId=66f000000000000000000010' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns your tiers in data. data is {} when your community has no tiers: 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.

RuleTiers info fetched successfully

data#objectALWAYS
One key per tier, named as in your community, in the order they are set up. Each tier maps its level names to the XP the level needs, as text such as 500 XP; the unit is your community's XP name. {} when your community has no tiers.

Eg{ ... }

{
  "status": "success",
  "message": "Tiers info fetched successfully",
  "data": {
    "Bronze": {
      "Level 1": "0 XP",
      "Level 2": "500 XP"
    },
    "Silver": {
      "Level 3": "1500 XP",
      "Level 4": "3000 XP"
    }
  }
}

Errors#

Errors on this endpoint have no machine-readable code; branch on the HTTP status and read message. A key without getTiersInfo gets 401, not 403. A malformed communityId returns 500, not 400.

Fix the request02

400Fix the request
message says which: Community ID is required (send communityId), or Community not found (no community has this ID; send your own community's ID).
401Fix the request
The key is missing, invalid or expired, it's a personal key, or it lacks getTiersInfo (message is then Your api key does not have permission to access this action). Send Authorization: Bearer <API_KEY> with a current Community API key, and add Get Tier Infos in Settings > Integration > API Keys.

Retry with backoff01

500Retry with backoff
communityId isn't a 24-character hex ID, the tiers could not be read, or the key could not be checked (Authentication failed). Check the ID, then retry with exponential backoff.

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 500; use bounded exponential backoff. Over the rate limit, requests return 429; wait for the window to reset, then retry.

{
  "status": "error",
  "message": "Community not found"
}

Next step#

Get User DataPOST/v1/users/infoRead a trader's XP and current level to compare with these thresholds.