Welcome

Backend API

Welcome routes come from llm_d_lens/dashboard/router.py. They return the latest issue snapshot only. A backend background task refreshes that snapshot every 60 seconds; request handlers filter it per caller. Cluster capacity, service tables, deployment activity and usage remain on their owning APIs.

Both routes require an authenticated session and cluster:cluster:read. Every issue is also filtered by the caller's reachable clusters and by the permissions of the issuing domain. An inaccessible explicit clusterId returns 403 without resource details.

Get the Welcome overview

Return the scoped issue envelope for the Welcome page. When a snapshot exists, refresh=true schedules another background check and returns the current snapshot immediately; it does not block on remote sources.

REST API

GET /api/v1/welcome/overview

Query parameters:

• clusterId (string, optional): one accessible cluster.
• refresh (boolean, default false): schedule a background snapshot refresh.

Response: WelcomeOverview.

{
  "generatedAt": "2026-10-18T12:41:03Z",
  "scope": {
    "mode": "all",
    "clusters": [{ "id": "cluster-a", "name": "prod-a" }]
  },
  "issues": {
    "state": "complete",
    "generatedAt": "2026-10-18T12:41:03Z",
    "observedAt": "2026-10-18T12:40:30Z",
    "stale": false,
    "coverage": { "observed": 1, "expected": 1, "unit": "clusters" },
    "data": [
      {
        "id": "model.provider_unhealthy|cluster-a|model_service|msg-123",
        "code": "model.provider_unhealthy",
        "severity": "warning",
        "category": "model-service",
        "title": "model-alpha: 1 provider(s) not ready",
        "message": "At least one configured provider is unhealthy.",
        "clusterId": "cluster-a",
        "resource": { "type": "model_service", "id": "msg-123", "name": "model-alpha" },
        "evidence": { "providers": { "ready": 1, "active": 2 } },
        "primaryAction": {
          "intent": "inspect_providers",
          "view": "admin/model-service",
          "params": { "clusterId": "cluster-a", "groupId": "msg-123" },
          "permission": "model-service:group:read"
        }
      }
    ]
  }
}

The response does not contain hardware summaries, cluster capacity, service rows, deployment activity, token totals or AI provider configuration.

Python API

import asyncio

from llm_d_lens.dashboard.service import default_service

async def main(principal) -> None:
    # `principal` normally comes from the authenticated request session.
    overview = await default_service().welcome_overview(principal, cluster_id="cluster-a")
    for issue in overview.issues.data or []:
        print(issue.severity, issue.code, issue.title)

asyncio.run(main(principal))

List current issues

Return the same normalized current findings with filters and cursor pagination. This is the API behind View all issues.

REST API

GET /api/v1/welcome/issues

Query parameters:

• clusterId (string, optional): one accessible cluster.
• severity (critical, warning, info, optional).
• category (cluster, model-service, deployment, storage, model-cache, monitoring, ai-provider, access, optional).
• search (string, optional): matches issue and resource identity, or text.
• cursor (string, optional): opaque cursor from nextCursor.
• limit (integer, default 25, range 1..100).

Response: WelcomeIssuesResponse with snapshotId, total, items, nextCursor and restarted.

{
  "generatedAt": "2026-10-18T12:41:03Z",
  "snapshotId": "8e4f...",
  "total": 3,
  "items": [],
  "nextCursor": null,
  "restarted": false
}

Cursors include the snapshot identity. If the snapshot expired or findings changed, the server sets restarted: true and returns the first page.

Python API

import asyncio

from llm_d_lens.dashboard.service import default_service

async def main(principal) -> None:
    page = await default_service().alerts(principal, severity="critical", limit=25)
    print(page.total)
    for issue in page.items:
        print(issue.cluster_name, issue.title)

asyncio.run(main(principal))

Related endpoints

• GET /api/v1/ai-providers: provider list used by the Welcome composer.
• GET /api/cluster/overview: complete cluster hardware and component payload.
• GET /api/v1/model-service/admin/gateway/status: Gateway and IPP state.
• GET /api/v1/monitoring/cluster-stack/status: monitoring stack detail.