> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom dashboards
> Build live monitoring dashboards from reusable code snippets
Custom dashboards let you build live monitoring views for your infrastructure by combining reusable code snippets into a configurable grid layout. Each widget runs a snippet that queries the Akua API and displays the result as a table, stat, JSON tree, or log output.
Snippets use sandboxed JavaScript execution with the same `platform.request()` API, V8 isolation, and security model used by Akua's automation layer. You can write snippets by hand and preview them before saving.
## How it works
Dashboards are built from two building blocks:
* **Snippets**: JavaScript functions that query the Akua API and return data. Each snippet has a display type (table, stat, JSON, or logs) that controls how the result is rendered.
* **Dashboards**: Grid layouts that arrange snippets as widgets. Each widget can span 1–4 columns and runs its snippet automatically when you open the dashboard.
You write a snippet once, then reuse it across multiple dashboards. When you update a snippet, every dashboard that uses it picks up the change.
## Creating a snippet
Navigate to **Dashboards → Snippets** tab and click **New snippet**.
Snippets are `async` JavaScript functions that use `platform.request()` to call the [Akua API](/apis/introduction). The workspace header is injected automatically, so you don't need to pass authentication or workspace IDs.
```javascript theme={null}
async () => {
const res = await platform.request({
method: "GET",
path: "/v1/clusters",
});
if (res.status !== 200) throw new Error(JSON.stringify(res.body));
return res.body.data.map(c => ({
name: c.name,
status: c.kaas?.status ?? "imported",
version: c.kaas?.version ?? "—",
}));
}
```
The editor includes a side-by-side preview. Click **Run** to execute the snippet and see the result before saving.
Use the **Examples** dropdown in the snippet editor to load pre-built snippets for common tasks like listing clusters, counting installs, or generating status reports.
### Display types
The display type controls how the snippet result is rendered in dashboard widgets:
| Display type | Return value | Use case |
| ------------ | ----------------------- | --------------------------- |
| **Table** | Array of objects | List resources with columns |
| **Stat** | Single number or string | KPIs, counts, status values |
| **JSON** | Any object | Structured data, breakdowns |
| **Logs** | String | Text reports, log output |
### The `platform.request()` API
Snippets run in a sandboxed environment with access to a single function:
```javascript theme={null}
const response = await platform.request({
method: "GET" | "POST" | "PUT" | "DELETE",
path: "/v1/...",
body: { ... }, // optional, for POST/PUT
});
// response.status — HTTP status code
// response.body — parsed JSON response
```
All requests are authenticated and scoped to the current workspace. See the [API reference](/apis/introduction) for available endpoints.
Snippets execute server-side in an isolated sandbox. They cannot access `require`, `process`, `fs`, or any Node.js APIs; only `platform.request()` is available.
## Creating a dashboard
Navigate to **Dashboards** tab and click **New dashboard**. Give it a name and optional description, then click **Create dashboard** to open the builder.
### The dashboard builder
Dashboards open in **view mode** by default, showing your widgets in a live grid. Click **Edit** to enter edit mode, where overlay controls appear on each widget:
* **Move up/down**: reorder widgets in the grid
* **Resize (−/+)**: adjust column span from 1/4 to full width
* **Edit snippet**: jump to the snippet editor
* **Delete**: remove the widget
Use the **Add widget** bar at the bottom to select a snippet and add it to the dashboard. Click **Save** when you're done, or **Done** to return to view mode.
Use **Cmd+S** (Mac) or **Ctrl+S** (Windows/Linux) to save without clicking the button.
## Workspace scoping
Snippets and dashboards follow the same workspace scoping as other Akua resources:
* **When a workspace is selected**: you see snippets and dashboards belonging to that workspace.
* **When "All workspaces" is selected**: you see snippets and dashboards from all workspaces you have access to.
Snippet API calls are always scoped to the workspace the snippet belongs to.
## API
Manage snippets and dashboards programmatically.
Create, update, run, and delete snippets.
Create dashboards and manage their widget layout.
## Related topics
API endpoints for snippets and beyond.
How workspaces organize resources.