# Retrieve the points ranking

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

Operation ID: `reports.rankings.list` · API v3

Returns the same points ranking as the gamification ranking endpoint. Either the `reports.read` or the `rankings.read` permission grants access.

Results are limited to the products and users accessible with the current credentials. Each entry includes the user's name and avatar only when the credentials also have the `users.read` permission.

Required permissions: `reports.read`, `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