# Retrieve the points ranking

`GET https://api.cademi.com.br/api/v3/gamification/rankings`

Operation ID: `rankings.list` · API v3

Returns the users ranked by points earned in the selected period. When `period` is omitted, all-time points are used; when `limit` is omitted, up to 100 positions are returned.

Results are limited to the products and users accessible with the current credentials. Filtering by `product_id` narrows that scope and never widens it: requesting products outside the scope returns an empty ranking.

Each entry includes the user's name and avatar only when the credentials also have the `users.read` permission; otherwise the `user` object is `null`.

Rankings are eventually consistent. Manual point adjustments are reflected on the next request, while automatically awarded points may take up to `cache_ttl_seconds` to appear.

Required permissions: `rankings.read`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `period` | query | string, one of `all`, `today`, `last_7_days`, `last_30_days`, `custom` | no |  |
| `from` | query | string (date) | no | Required when period is custom. |
| `to` | query | string (date) | no | Required when period is custom. |
| `product_id` | query | array of string | no |  |
| `limit` | query | integer | no |  |

## Responses

### 200

Returns the ranking for the requested period.

Body: `data`: Ranking.

Fields of Ranking:

| Field | Type | Required | Description |
|---|---|---|---|
| `cache_ttl_seconds` | integer | yes |  |
| `entries` | array of object | yes |  |
| `generated_at` | string (date-time) | yes |  |
| `object` | string, one of `ranking` | yes |  |
| `period` | object | yes |  |
| `scope` | object | yes |  |
| `summary` | object | yes |  |

### 400

The request contains an unsupported query parameter.

Body: Error.

### 401

The credential is missing, malformed, expired, or revoked.

Body: Error.

### 403

The current credentials do not have the permission required by this operation.

Body: Error.

### 422

The request body or query parameters failed validation.

Body: ValidationFailed.

Full schema: https://cademi.dev/openapi/v3.json