---
title: Custom dashboards
summary: The Observability API allows you to programmatically define custom dashboards to view in the Observability web interface.
url: https://www.fastly.com/documentation/reference/api/observability/custom-dashboards
---

The Observability API allows you to programmatically define custom
dashboards to view in the Observability web interface.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `description` | string | A short description of the dashboard. |
| `items` | array | A list of <a href="#dashboard-item">dashboard items</a>. |
| `name` | string | A human-readable name. |
| `created_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `created_by` | string | The ID of the user who created the dashboard. (Read-only) |
| `id` | string | Dashboard identifier (UUID). (Read-only) |
| `updated_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `updated_by` | string | The ID of the user who last modified the dashboard. (Read-only) |

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `data_source` | object | <a href="#data-source">An object</a> which describes the data to display. |
| `id` | string | Dashboard item identifier (UUID). (Read-only) |
| `span` | integer | The number of columns for the dashboard item to span. Dashboards are rendered on a 12-column grid on "desktop" screen sizes. |
| `subtitle` | string | A human-readable subtitle for the dashboard item. Often a description of the visualization. |
| `title` | string | A human-readable title for the dashboard item. |
| `visualization` | object | <a href="#visualization">An object</a> which describes the data visualization to display. |

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `config` | object | <a href="#data-source-config">Configuration options</a> for the selected data source. |
| `type` | string | The source of the data to display. |

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `metrics` | array | The metrics to visualize. Valid options are defined by the selected <a href="#field_data_source">data source</a>. |

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `config` | object | <a href="#visualization-config">Configuration options</a> for the given visualization. |
| `type` | string | The type of visualization to display. |

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `calculation_method` | string | (Optional) The aggregation function to apply to the dataset. |
| `format` | string | (Optional) The units to use to format the data. |
| `plot_type` | string | The type of chart to display. |

## API endpoints

### List all custom dashboards

**GET** `/observability/dashboards`

List all custom dashboards.

### Create a new dashboard

**POST** `/observability/dashboards`

Create a new dashboard.

### Retrieve a dashboard by ID

**GET** `/observability/dashboards/{dashboard_id}`

Retrieve a dashboard by ID.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `dashboard_id` | string | path | Yes | Dashboard identifier (UUID). |

### Delete an existing dashboard

**DELETE** `/observability/dashboards/{dashboard_id}`

Delete an existing dashboard.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `dashboard_id` | string | path | Yes | Dashboard identifier (UUID). |

### Update an existing dashboard

**PATCH** `/observability/dashboards/{dashboard_id}`

Update an existing dashboard.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `dashboard_id` | string | path | Yes | Dashboard identifier (UUID). |