# Get requests per connected user
URL: https://musicapi.com/docs/reference/usage-top-users.md

`GET https://api.musicapi.com/public/analytics/top-users`

Section: Billing and usage.
Product: MusicAPI Core and MusicAPI Managed Transfers.
Auth: Basic, DocsSession (any one of them). Use Basic with your Client ID and Client Secret from your server only.

Your connected users in the range, the busiest first, with their requests, error rate and last request. Page with `limit` and `offset`; `total` is the number of users. Requires Client Secret authentication. Not billed.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | The first day of the range (UTC), for example `2026-10-01`. The day counts. |
| `endDate` | string | yes | The last day of the range (UTC). The day counts, so `startDate` = `endDate` is one day. The range may hold at most 366 days, or 31 days for an `hourly` series. |
| `integrationType` | spotify \\| appleMusic \\| youtube \\| tidal \\| resso \\| boomplay \\| amazonMusic \\| deezer \\| pandora \\| soundCloud \\| youtubeMusic \\| napster \\| qobuz \\| qqMusic \\| yandexMusic \\| vkMusic \\| anghami \\| zvuk \\| gaana \\| jiosaavn \\| audiomack | no | Count only the requests for this music service. Leave it out for every service. |
| `limit` | number | no | The number of rows. Default: `20`. |
| `offset` | number | no | The number of rows to skip, for the next page. Default: `0`. |

## Response 200

The user with the most requests first.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes |  |
| `data[].uuid` | string | yes | The `integrationUserUUID` of the connected user. |
| `data[].integration_type` | string | yes | The music service. |
| `data[].total_requests` | string | yes | Requests for this user. A decimal string, so a large count stays exact. |
| `data[].error_count` | string | yes | Requests for this user that failed. A decimal string, so a large count stays exact. |
| `data[].error_rate` | number | yes | `error_count` / `total_requests` in percent, two decimals. |
| `data[].avg_response_time_ms` | number | yes | The average response time in milliseconds. |
| `data[].last_seen` | string | yes | The time of the last request in UTC, `YYYY-MM-DD hh:mm:ss`. |
| `total` | number | yes | The number of connected users with requests in the range. |
| `limit` | number | yes | The `limit` of this page. |
| `offset` | number | yes | The `offset` of this page. |

```json
{
  "data": [
    {
      "uuid": "string",
      "integration_type": "string",
      "total_requests": "string",
      "error_count": "string",
      "error_rate": 0,
      "avg_response_time_ms": 0,
      "last_seen": "string"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}
```

## Errors

- 400: A date is missing or not valid, `endDate` is before `startDate`, or the range is too long.
- 401: The request has no credentials.
- 403: The request does not use Client Secret authentication.
- 429: Your account sent more calls this minute than its rate limit allows.

## Example

```bash
curl https://api.musicapi.com/public/analytics/top-users \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```