# Analytics endpoints (Admin API)

> 16 FeatherPanel Admin API endpoints from admin/kpi/analytics.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/admin/kpi/analytics/

Defined in [`backend/app/routes/admin/kpi/analytics.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php). Authentication used here: **Admin**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/admin/analytics/overview`

- Auth: Admin
- Permission: `admin.dashboard.view`
- Route name: `admin-analytics-overview`
- Controller: [`OverviewController::getOverview`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/OverviewController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L27)

**Get the KPI overview for a date range** Growth against the previous period, active users, module counts, node capacity and overcommit, top consumers, tickets and activity. Disabled modules are left out.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | no | First day (Y-m-d). Defaults to 29 days before "to". |
| `to` | query | string (date) | no | Last day (Y-m-d). Defaults to today. |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/overview" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Overview retrieved successfully · `400` Invalid date range · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/overview`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-overview`
- Controller: [`AnalyticsController::getUserOverview`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L38)

**Get user analytics overview** Retrieve comprehensive overview of user statistics including total, active, banned, verified, and 2FA enabled users.

Response data: [`UserAnalyticsOverview`](https://featherpanel.com/docs/api/schemas/#schema-useranalyticsoverview)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `total` | integer | Total user count |
| `active` | integer | Active users (not banned) |
| `banned` | integer | Banned users |
| `verified` | integer | Email verified users |
| `two_fa_enabled` | integer | Users with 2FA enabled |
| `unverified` | integer | Unverified users |
| `percentage_verified` | number (float) | Percentage of verified users |
| `percentage_banned` | number (float) | Percentage of banned users |
| `percentage_two_fa` | number (float) | Percentage of users with 2FA |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/overview" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` User analytics overview retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/by-role`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-by-role`
- Controller: [`AnalyticsController::getUsersByRole`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L49)

**Get user distribution by roles** Retrieve user distribution across different roles with counts and percentages.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `total_users` | integer | Total number of users |
| `roles` | RoleDistribution\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/by-role" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` User role distribution retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/registration-trend`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-registration-trend`
- Controller: [`AnalyticsController::getRegistrationTrend`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L60)

**Get user registration trend** Retrieve user registration trends over a specified time period.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | Number of days to look back (default: 30) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `period_days` | integer | Number of days in the period |
| `data` | RegistrationTrend\[\] |  |
| `total_new_users` | integer | Total new users in the period |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/registration-trend" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Registration trend retrieved successfully · `400` Bad request - Invalid days parameter · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/top-by-servers`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-top-by-servers`
- Controller: [`AnalyticsController::getTopUsersByServers`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L71)

**Get top users by server count** Retrieve the users with the most servers.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Number of top users to retrieve (default: 10) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `limit` | integer | Limit applied |
| `users` | TopUser\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/top-by-servers" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Top users retrieved successfully · `400` Bad request - Invalid limit parameter · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/activity`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-activity`
- Controller: [`AnalyticsController::getUserActivity`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L82)

**Get user activity summary** Retrieve user activity summary for a specified time period.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `hours` | query | integer | no | Number of hours to look back (default: 24) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `period_hours` | integer | Number of hours in the period |
| `new_users` | integer | New users in the period |
| `active_users` | integer | Active users in the period |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/activity" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` User activity retrieved successfully · `400` Bad request - Invalid hours parameter · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/dashboard`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-dashboard`
- Controller: [`AnalyticsController::getDashboard`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L93)

**Get comprehensive user analytics dashboard** Retrieve all user analytics data in a single comprehensive dashboard view.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `overview` | UserAnalyticsOverview |  |
| `by_role` | object | User distribution by role |
| `registration_trend_7d` | object | 7-day registration trend |
| `registration_trend_30d` | object | 30-day registration trend |
| `top_users` | object | Top users by server count |
| `activity_24h` | object | 24-hour activity summary |
| `activity_7d` | object | 7-day activity summary |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/dashboard" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Analytics dashboard retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/banned`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-banned`
- Controller: [`AnalyticsController::getBannedUsers`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L104)

**Get banned users statistics** Retrieve statistics and information about banned users.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Number of recent banned users to retrieve (default: 20) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `total_banned` | integer | Total number of banned users |
| `recent_banned_users` | object\[\] | Recently banned users |
| `ban_trend_30d` | object\[\] | 30-day ban trend |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/banned" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Banned users statistics retrieved successfully · `400` Bad request - Invalid limit parameter · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/security`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-security`
- Controller: [`AnalyticsController::getSecurityStats`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L115)

**Get user security statistics** Retrieve statistics about user security features (2FA, email verification).

| Response `data` field | Type | Description |
| --- | --- | --- |
| `total_users` | integer | Total number of users |
| `two_fa_enabled` | integer | Users with 2FA enabled |
| `email_verified` | integer | Users with verified email |
| `fully_secured` | integer | Users with both 2FA and email verified |
| `not_secured` | integer | Users with neither 2FA nor email verified |
| `percentage_two_fa` | number (float) | Percentage with 2FA |
| `percentage_email_verified` | number (float) | Percentage with verified email |
| `percentage_fully_secured` | number (float) | Percentage fully secured |
| `percentage_not_secured` | number (float) | Percentage not secured |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/security" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Security statistics retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/users/growth`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-users-growth`
- Controller: [`AnalyticsController::getGrowthRate`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L126)

**Get user growth rate statistics** Retrieve user growth rate statistics comparing recent periods.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `last_7_days` | integer | New users in last 7 days |
| `previous_7_days` | integer | New users in previous 7 days |
| `growth_rate_7d` | number (float) | 7-day growth rate percentage |
| `last_30_days` | integer | New users in last 30 days |
| `previous_30_days` | integer | New users in previous 30 days |
| `growth_rate_30d` | number (float) | 30-day growth rate percentage |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/users/growth" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Growth rate statistics retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/activity/trend`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-activity-trend`
- Controller: [`AnalyticsController::getActivityTrend`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L139)

**Get activity trend over time** Retrieve activity trends for a specified time period.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | Number of days to look back (default: 7) |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/activity/trend" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Activity trend retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/activity/top`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-activity-top`
- Controller: [`AnalyticsController::getTopActivities`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L150)

**Get top activities by type** Retrieve the most common activity types.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Number of top activities to retrieve (default: 10) |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/activity/top" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Top activities retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/activity/breakdown`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-activity-breakdown`
- Controller: [`AnalyticsController::getActivityBreakdown`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L161)

**Get activity breakdown by type** Retrieve activity distribution for pie chart visualization.

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/activity/breakdown" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Activity breakdown retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/activity/recent`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-activity-recent`
- Controller: [`AnalyticsController::getRecentActivities`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L172)

**Get recent activities** Retrieve recent user activities with user information.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Number of recent activities to retrieve (default: 20) |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/activity/recent" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Recent activities retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/activity/stats`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-activity-stats`
- Controller: [`AnalyticsController::getActivityStats`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L183)

**Get activity statistics summary** Retrieve overall activity statistics.

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/activity/stats" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Activity statistics retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/analytics/activity/hourly`

- Auth: Admin
- Permission: `admin.users.list`
- Route name: `admin-analytics-activity-hourly`
- Controller: [`AnalyticsController::getHourlyActivity`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/KPI/AnalyticsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/kpi/analytics.php#L194)

**Get hourly activity distribution** Retrieve activity distribution by hour for heatmap visualization.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | Number of days to look back (default: 7) |

```bash
curl -X GET "$PANEL_URL/api/admin/analytics/activity/hourly" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Hourly activity retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions