# Get provider top savers

> Returns the top users by realized (captured) savings for a provider, ranked descending (max 3)

Source: https://docs.levelfour.ai/api-reference/providers/get-providers-by-id-recommendations-top-savers


## GET /api/v1/providers/{provider_id}/recommendations/top-savers

Returns the top users by realized (captured) savings for a provider, ranked descending (max 3)

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `provider_id` (path, string, required)

### Responses

#### 200: Successful Response

- `success` (boolean, default `true`)
- `timestamp` (date-time string)
- `data` (object, required): Top savers leaderboard data for a provider.
  - `items` (array of object): Users ranked by captured savings descending (max 3); empty when no realized savings exist
    - `user_id` (string, required): Stable identifier for the user, used as the list key
    - `email` (string, required): Email of the user who approved the realized savings
    - `avatar_url` (string, nullable): User avatar URL, null when not resolved
    - `captured_savings` (number, required): Monthly USD savings captured (realized) from recommendations this user approved
    - `trend_pct` (number, default `0`): Signed period-over-period percent change of this user's captured savings (0 when no prior period)

#### Errors

- `400`: Bad Request
- `401`: Authentication Error
- `403`: Authorization Error
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error

Body of `400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`:

- `success` (`false`, required)
- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `details` (any)
- `timestamp` (date-time string, required)