Admin API: platform stats and user management

The Admin API provides platform-level visibility into user metrics and account management. All endpoints require superuser authentication and are mounted under /api/admin/.

These endpoints are restricted to superuser accounts. Regular users receive a 403 Forbidden response.

GET /api/admin/stats

Return aggregate statistics for the admin dashboard. Headers:

string

required

Bearer <access_token> — must be a superuser token.

curl --request GET \
  --url http://localhost:8000/api/admin/stats \
  --header "Authorization: Bearer <access_token>"

Response:

number

required

Total number of registered user accounts.

number

required

Number of users with subscription_status set to active.

number

required

Number of users who registered in the last 7 days.

number

required

Number of users who have verified their email address.

{
  "total_users": 1250,
  "active_subscriptions": 340,
  "new_users_7d": 42,
  "verified_users": 980
}

GET /api/admin/users

Return a paginated list of all user accounts, ordered by creation date (newest first). Headers:

string

required

Bearer <access_token> — must be a superuser token.

Query parameters:

number

default:"1"

Page number. Must be 1 or greater.

number

default:"20"

Number of users per page. Must be between 1 and 100.

curl --request GET \
  --url "http://localhost:8000/api/admin/users?page=1&limit=20" \
  --header "Authorization: Bearer <access_token>"

import requests

response = requests.get(
    "http://localhost:8000/api/admin/users",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"page": 1, "limit": 20},
)
data = response.json()
print(f"Showing {len(data['users'])} of {data['total']} users")

Response:

object[]

required

Array of user objects for the requested page.

Show user properties

string

required

UUID of the user.

string

required

User’s email address.

string

User’s display name.

boolean

required

Whether the account is active.

boolean

required

Whether the email is verified.

string

required

Current subscription status.

string

required

Current subscription tier.

string

required

ISO 8601 account creation timestamp.

ISO 8601 timestamp of the last login, or null.

number

required

Total number of users across all pages.

number

required

Current page number.

number

required

Number of users per page.

number

required

Total number of pages.

{
  "users": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "user@example.com",
      "full_name": "Jane Smith",
      "is_active": true,
      "is_verified": true,
      "subscription_status": "active",
      "subscription_tier": "pro",
      "created_at": "2026-04-01T10:30:00Z",
      "last_login_at": "2026-04-09T09:00:00Z"
    }
  ],
  "total": 1250,
  "page": 1,
  "limit": 20,
  "pages": 63
}

Overview

Endpoints

Admin API: platform stats and user management

GET /api/admin/stats

GET /api/admin/users

​GET /api/admin/stats

​GET /api/admin/users

GET /api/admin/stats

GET /api/admin/users