# Get tier configuration

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

- Endpoint: `GET https://api.returning.ai/v1/xp-settings/tiers-info`
- Section: Gamification / General
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `getTiersInfo` (Shown in the dashboard as "Get Tier Infos")
- 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/get-tier-configuration

## 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.

**Instead:** Use [Get User Data](https://docs.returning.ai/api-reference/users/get-user-data.md) instead to read one trader's XP and current level.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `getTiersInfo`

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.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | Your community's ID. Send the community that owns your API key. (24-character hex ID) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `getTiersInfo`. (`Bearer <API_KEY>`) |

### Example request

```bash
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.

### 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. (`Tiers info fetched successfully`) |
| `data` | `object` | always | 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. |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | `message` says which: `Community ID is required` (send `communityId`), or `Community not found` (no community has this ID; send your own community's ID). |
| 401 | - | 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 backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | `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](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`. Read a trader's XP and current level to compare with these thresholds.
- [See how much XP traders earned on a day with Get daily user XP and coin changes](https://docs.returning.ai/api-reference/gamification/get-daily-user-xp-and-coin-changes.md): `POST /v1/users/activity/daily`.