> ## Documentation Index
> Fetch the complete documentation index at: https://copilot-api.nick3.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor usage with the Admin UI

> Use the built-in web dashboard at /admin to inspect request history, account stats, and per-request details without leaving your browser.

Copilot API includes a built-in web app that lets you inspect account runtime status and request history captured by the proxy. You can filter requests by model, endpoint, or error state, drill into individual request metadata, and share deep links to specific views — all without installing any extra tooling.

## Opening the Admin UI

<Steps>
  <Step title="Start the proxy">
    Run the proxy with your usual command:

    ```bash theme={null}
    npx @nick3/copilot-api@latest start
    ```
  </Step>

  <Step title="Open the UI in your browser">
    Navigate to:

    ```
    http://localhost:4141/admin
    ```

    Replace `4141` with the port you set if you changed the default.
  </Step>
</Steps>

## UI features

### Accounts view

The Accounts view shows a KPI overview across all registered accounts, including error rate and average tokens per request. You can filter and sort the account list. Click any account to jump directly to the Requests view with that account's filter pre-applied.

### Requests view

The Requests view lets you search and filter your request history. Available filters include:

* `account_id` — the account that handled the request
* `model` — the client-requested model or the upstream model
* `endpoint` — the endpoint path
* `status` — HTTP response status
* `has_error` — show only requests that returned errors
* Time range — preset windows (15 min, 1 h, 6 h, 24 h, 7 days) or a custom date/time range

Requests paginate using cursor-based pagination. Click **Next** to load the following page.

### Request detail

Click any row in the Requests view to open the request detail page. From there you can:

* Use the **Back** button to return to the Requests view with your filters preserved
* View summary fields — each one links back into the Requests view with that value as a filter
* Inspect the full request metadata in the JSON viewer, which supports search/highlight, expand/collapse, copy, and download

### Header controls

The top-right corner of the UI exposes three controls:

* **Motion** — choose `Magic`, `Subtle`, or `Off`. Automatically forced to `Off` when your OS has reduced motion enabled.
* **Theme** — choose `System`, `Light`, or `Dark`.
* **Admin token** — open a dialog to save and test your admin token, which is stored in `sessionStorage` and sent as the `x-admin-token` header.

### Deep links

The Admin UI uses hash routing. You can copy and share URLs that preserve your current view and filters:

```
http://localhost:4141/admin/#/requests?account_id=octocat&has_error=1
```

## Data storage and retention

The proxy stores request metadata in `admin.sqlite` under the app data directory:

* **Linux / macOS:** `~/.local/share/copilot-api/admin.sqlite`
* **Windows:** `%USERPROFILE%\.local\share\copilot-api\admin.sqlite`

**What is stored:** request metadata only — model names, endpoints, token counts, timing, and error summaries. GitHub tokens, Copilot tokens, and request/response content are never stored.

**Retention:** up to 14 days, capped at 200,000 rows. Older entries are cleaned up automatically.

## Access control

<Note>
  When you access the Admin UI from `localhost`, `127.0.0.1`, or `::1`, no token is required. The Admin UI and API are restricted to loopback access by default.
</Note>

To allow access from a non-loopback address (for example, a remote machine or a LAN IP), set the `ADMIN_TOKEN` environment variable on the server before starting the proxy:

```bash theme={null}
ADMIN_TOKEN=your_admin_token_here npx @nick3/copilot-api@latest start
```

Then include the token in every request using one of:

```
x-admin-token: your_admin_token_here
```

```
Authorization: Bearer your_admin_token_here
```

<Warning>
  Tokens in URL query parameters are intentionally not supported. Always pass the token as a header.
</Warning>

**Error codes:**

* `403 Forbidden` — the request came from a non-loopback address and `ADMIN_TOKEN` is not set on the server.
* `401 Unauthorized` — `ADMIN_TOKEN` is set but you did not include the token in the request header.

## Admin API endpoints

You can query the same data programmatically using the Admin API:

| Endpoint                                  | Description                                                                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/admin/meta`                     | Returns database metadata: path, retention settings, and row count.                                                                                                                                                    |
| `GET /api/admin/accounts?include_stats=1` | Lists all accounts with runtime status. Pass `include_stats=1` to include aggregated request statistics per account.                                                                                                   |
| `GET /api/admin/requests`                 | Returns paginated request logs. Supports filters: `account_id`, `upstream_model`, `client_model`, `status`, `has_error`, `from_ms`, `to_ms`. Paginate using `cursor_id` from the previous response's `next_cursor_id`. |
| `GET /api/admin/requests/:requestId`      | Returns the full metadata record for a single request by its ID.                                                                                                                                                       |

<CodeGroup>
  ```bash Loopback (no token required) theme={null}
  curl "http://localhost:4141/api/admin/meta"
  ```

  ```bash Remote access (token required) theme={null}
  curl -H "x-admin-token: your_admin_token_here" \
    "http://localhost:4141/api/admin/accounts?include_stats=1"
  ```

  ```bash Filter and paginate requests theme={null}
  # First page — only errored requests
  curl "http://localhost:4141/api/admin/requests?limit=50&has_error=1"

  # Next page — use next_cursor_id from the previous response
  curl "http://localhost:4141/api/admin/requests?limit=50&cursor_id=<next_cursor_id>"
  ```

  ```bash Single request detail theme={null}
  curl "http://localhost:4141/api/admin/requests/<requestId>"
  ```
</CodeGroup>