# Top donors

**`GET /v1/stats/top`** · Secret or public key · scope `stats:read`

The donors with the largest totals for today, this week, month, year or all time. Donations from all connected sources are counted and converted to rubles. Donors with the same name in different sources are counted as one.

## Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `period` | query | string, values: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME`, default `ALL_TIME` | `DAY` — today from 00:00, `WEEK` — this week from Monday, `MONTH` — this month, `YEAR` — this year, `ALL_TIME` — all time. Boundaries follow `timeZone`. `ALL_TIME` by default. |
| `limit` | query | integer, 1–100, default `10` | How many donors to return: 1 to 100, 10 by default. |
| `timeZone` | query | string, default `Europe/Moscow` | The time zone used for period boundaries, for example `Asia/Novosibirsk`. `Europe/Moscow` by default. |

## Responses

- `200` — OK
- `400` — A parameter is invalid, or the key was sent in the request address: [`invalid_parameter`](https://developers.donatty.com/en/errors/invalid_parameter.md), [`token_in_query`](https://developers.donatty.com/en/errors/token_in_query.md)
- `401` — The key is missing, unknown, deleted or expired: [`missing_token`](https://developers.donatty.com/en/errors/missing_token.md), [`invalid_token`](https://developers.donatty.com/en/errors/invalid_token.md), [`token_expired`](https://developers.donatty.com/en/errors/token_expired.md)
- `403` — Wrong kind of key, the key lacks the `stats:read` scope, or the public key came from an address that is not in its list: [`wrong_token_type`](https://developers.donatty.com/en/errors/wrong_token_type.md), [`insufficient_scope`](https://developers.donatty.com/en/errors/insufficient_scope.md), [`origin_not_allowed`](https://developers.donatty.com/en/errors/origin_not_allowed.md)
- `429` — Rate limit exceeded: [`rate_limited`](https://developers.donatty.com/en/errors/rate_limited.md)
- `500` — The request failed on our side: [`internal_error`](https://developers.donatty.com/en/errors/internal_error.md)
- `503` — The API is temporarily unavailable: [`service_unavailable`](https://developers.donatty.com/en/errors/service_unavailable.md)

## Example response

```json
{
  "period": "WEEK",
  "from": "2026-11-08T21:00:00Z",
  "to": "2026-11-15T21:00:00Z",
  "items": [
    {
      "rank": 1,
      "name": "Alex",
      "total": {
        "value": "12500.00",
        "currency": "RUB"
      }
    },
    {
      "rank": 2,
      "name": "Maria",
      "total": {
        "value": "4300.75",
        "currency": "RUB"
      }
    },
    {
      "rank": 3,
      "name": "Ivan",
      "total": {
        "value": "1000.00",
        "currency": "RUB"
      }
    }
  ]
}
```

## Schemas

### Top

| Field | Type | Description |
|---|---|---|
| `period` | string, values: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME` | The period from the request. |
| `from` | string (date-time) | Start of the period. For `ALL_TIME`, `1970-01-01T00:00:00Z`. |
| `to` | string (date-time) | Start of the next period; that moment itself is not included. For `ALL_TIME`, the moment of the response. |
| `items` | list of objects |  |

### Money

| Field | Type | Description |
|---|---|---|
| `value` | string | Decimal amount with two fraction digits. |
| `currency` | string | ISO 4217 code. |
