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

# Dashboard

> Cached tenant business-health snapshot for KPI tiles

# Dashboard

Returns a cached, dashboard-ready snapshot of tenant operational health. Five sections (pipeline, performance, workforce, assets, and knowledge) map to dashboard KPI payloads. Near-zero AI cost at read time; aggregated from the intelligence layer.

## GET /dashboard

Tenant pulse snapshot.

**Query parameters:**

| Param        | Type    | Required | Description                                               |
| ------------ | ------- | -------- | --------------------------------------------------------- |
| `company_id` | string  | Yes      | Your tenant identifier                                    |
| `api_key`    | string  | Yes      | Your tenant API key                                       |
| `refresh`    | boolean | No       | Bypass cache and force a fresh snapshot (default `false`) |

**Response fields:**

| Field                  | Type   | Description                                                                           |
| ---------------------- | ------ | ------------------------------------------------------------------------------------- |
| `company_id`           | string | Tenant identifier                                                                     |
| `generated_at`         | string | ISO 8601 snapshot time                                                                |
| `cached_until`         | string | ISO 8601 cache expiry (5-minute TTL)                                                  |
| `sections.pipeline`    | object | Job lifecycle: totals, active, unassigned, in progress, completions, status breakdown |
| `sections.performance` | object | Last 30 days: completion rate, first-visit-fix rate, avg start/end delta (minutes)    |
| `sections.workforce`   | object | Engineer counts, active today, avg jobs per engineer, top engineer                    |
| `sections.assets`      | object | Customers, sites, vehicles, job types, job categories                                 |
| `sections.knowledge`   | object | Knowledge depth: intake records, outcomes, customer summaries, chat sessions          |

**Example:**

```bash theme={null}
curl -G "https://api.vh3connect.io/api:kP8T1CK7/dashboard" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key"
```

Force refresh:

```bash theme={null}
curl -G "https://api.vh3connect.io/api:kP8T1CK7/dashboard" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "refresh=true"
```

**Use cases:**

* **Home screen:** Single call to populate KPI tiles on first load.
* **Mobile summary:** Lightweight operational overview without running separate aggregate calls.
* **Health monitoring:** Internal or partner views of data coverage and knowledge-base completeness.
* **Scheduled snapshots:** n8n cron to archive pulse metrics for trend reporting.

**Notes:**

* Cached 5 minutes per tenant; uncached typically 200–800ms, cached under 10ms.
* Deterministic: the same underlying data yields the same metrics.
* Returns `502` if search or graph queries fail.