> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipfastai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin API: platform stats and user management

> Reference for admin-only endpoints: aggregate platform statistics and paginated user listing. Requires superuser access.

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

<Warning>
  These endpoints are restricted to superuser accounts. Regular users receive a `403 Forbidden` response.
</Warning>

***

## GET /api/admin/stats

Return aggregate statistics for the admin dashboard.

**Headers:**

<ParamField header="Authorization" type="string" required>
  `Bearer <access_token>` — must be a superuser token.
</ParamField>

```bash theme={null}
curl --request GET \
  --url http://localhost:8000/api/admin/stats \
  --header "Authorization: Bearer <access_token>"
```

**Response:**

<ResponseField name="total_users" type="number" required>
  Total number of registered user accounts.
</ResponseField>

<ResponseField name="active_subscriptions" type="number" required>
  Number of users with `subscription_status` set to `active`.
</ResponseField>

<ResponseField name="new_users_7d" type="number" required>
  Number of users who registered in the last 7 days.
</ResponseField>

<ResponseField name="verified_users" type="number" required>
  Number of users who have verified their email address.
</ResponseField>

```json theme={null}
{
  "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:**

<ParamField header="Authorization" type="string" required>
  `Bearer <access_token>` — must be a superuser token.
</ParamField>

**Query parameters:**

<ParamField query="page" type="number" default="1">
  Page number. Must be 1 or greater.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of users per page. Must be between 1 and 100.
</ParamField>

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

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

**Response:**

<ResponseField name="users" type="object[]" required>
  Array of user objects for the requested page.

  <Expandable title="user properties">
    <ResponseField name="id" type="string" required>UUID of the user.</ResponseField>
    <ResponseField name="email" type="string" required>User's email address.</ResponseField>
    <ResponseField name="full_name" type="string">User's display name.</ResponseField>
    <ResponseField name="is_active" type="boolean" required>Whether the account is active.</ResponseField>
    <ResponseField name="is_verified" type="boolean" required>Whether the email is verified.</ResponseField>
    <ResponseField name="subscription_status" type="string" required>Current subscription status.</ResponseField>
    <ResponseField name="subscription_tier" type="string" required>Current subscription tier.</ResponseField>
    <ResponseField name="created_at" type="string" required>ISO 8601 account creation timestamp.</ResponseField>
    <ResponseField name="last_login_at" type="string">ISO 8601 timestamp of the last login, or `null`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number" required>
  Total number of users across all pages.
</ResponseField>

<ResponseField name="page" type="number" required>
  Current page number.
</ResponseField>

<ResponseField name="limit" type="number" required>
  Number of users per page.
</ResponseField>

<ResponseField name="pages" type="number" required>
  Total number of pages.
</ResponseField>

```json theme={null}
{
  "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
}
```