# Dashboards

> Put saved reports side by side and look at all of them through one filter and time range, for example one customer's traffic

Source: https://www.apitraffic.io/docs/dashboards

A dashboard shows several [saved reports](https://www.apitraffic.io/docs/reports) side by side, as tiles. One filter, time range, bucket, environment and direction apply to every tile at once, so a dashboard of your customer reports becomes one customer's dashboard by filtering on that customer's tag.

![The Customer health dashboard: a filter bar with time range, bucket, environment and direction, then tiles for Active customers (1,284, up 6% vs previous 30 days), Usage by plan, Top customers as a bar chart and Customer latency (p95) trend as a line chart](https://www.apitraffic.io/docs/images/reports/dashboard.png)

Dashboards need the **Custom reports** feature in your plan. Open **Report dashboards** in the sidebar (next to **Reports**; the bucket's own overview is **Dashboard**).

If your plan stops including Custom reports, your dashboards stay listed and open **view only**: their tiles are shown but do not run, and you can still delete a dashboard.

## Creating a dashboard

**Save some reports**

Each tile shows a saved report. Build and save the reports you want first. See [Reports](https://www.apitraffic.io/docs/reports).

**Create the dashboard**

In **Report dashboards**, click **New dashboard**. Give it a **Name**, optionally a **Description**, choose **Who can see it**, and click **Save**. The new dashboard opens ready to arrange.

**Add tiles**

Choose a report in **Add a saved report** and click **Add tile**. Repeat for each report.

**Arrange and save**

Move and resize the tiles (see [Arranging tiles](#arranging-tiles)), then click **Save layout**.

## Tiles

Each tile runs its report and shows it the way the report is saved: a table, a chart or a single number. The tile's title links to the report, so you can open it in the builder. Under a chart, a tile shows the report's numbers the way its [Table setting](https://www.apitraffic.io/docs/reports#the-table-under-a-chart) says: behind **Show the numbers** (the default), open under the chart, or not at all (screen readers still get them). To change it, open the report and save it with another **Table** setting; every tile and embed that shows it follows. The [meta strip](https://www.apitraffic.io/docs/reports#how-the-numbers-are-made) is one short line at the top of each tile, under its title, saying where the numbers came from and whether they are approximate; click it for the details. A tile with no matching requests says **No requests matched** instead of drawing an empty chart. A tile that read stored requests only because its tag is not promoted says **Make this tile fast: promote customerId**, with **Promote** for owners and admins ([Make this report fast](https://www.apitraffic.io/docs/reports#make-this-report-fast)).

Tiles load on their own, up to four at a time. Changing the dashboard filter cancels tiles still loading with the old one. If one fails, it says why and offers **Try again**, and the others are not affected. Click a tile's refresh button to run it again.

If a tile's report was deleted, or made private by its owner, the tile says **This report was deleted or is no longer shared with you**. If you can edit the dashboard, click **Remove tile** on it; you do not need to enter **Edit layout**. Saving the dashboard also drops such tiles, and says how many.

On a tablet, every tile is at least half the width of the page; on a phone, tiles are shown one under another in the same order.

A dashboard holds up to 24 tiles. A report can be on more than one dashboard, and on the same dashboard more than once. Deleting a report removes its tiles.

## The dashboard filter

The bar at the top of a dashboard applies to every tile:

- **Filter every tile**: conditions in the same criteria language as reports, such as `tag:customerId == "org_8f2a"`. They are added to each report's own filter, so a tile counts the requests that match both.
- **Time range**: replaces each report's own time range.
- **Bucket**, **Environment** and **Direction** (all, inbound or outbound): replace each report's own scope when set.

Changing any of them runs every tile again. The change is only for your visit until you click **Save**, which keeps it for everyone who opens the dashboard. **Discard changes** puts back what was saved. If you cannot edit the dashboard, you can still change the filter for your visit, and **Reset** puts it back.

A filter on the firewall's decisions (such as `waf_action == "block"`) needs the [firewall](https://www.apitraffic.io/docs/waf/setup) in your plan. If your plan no longer includes it, a dashboard saved with such a filter still runs, and you can still rearrange and save it. Changing that filter (even for your visit), adding a report to the dashboard or changing the settings of a report on it is a new question, which needs the firewall again.

If your account shows the [sample data](https://www.apitraffic.io/docs/sample-data), **Bucket** also offers **Sample: Acme Store API** under **Sample data**: every tile then runs on the sample data, so you can see your dashboard filled in before your own traffic arrives. The sample data is only for your visit. It does not count as a change: **Save** keeps the dashboard's own bucket and environment (or the ones you chose before picking the sample data), and **Use my own data** in the banner goes back to them. **Discard changes** puts back what was saved and keeps the sample data showing.

### Example: one customer's dashboard

1. Save reports such as *Requests by endpoint*, *Errors by endpoint* and *p95 latency over time*, without a customer filter.
2. Put them on a dashboard called *Customer health*.
3. In **Filter every tile**, add `tag:customerId == "org_8f2a"`. Every tile now shows that customer only.
4. Change the value to look at another customer. Click **Save** only if the dashboard should open on that customer.

## Arranging tiles

Click **Edit layout**. Tiles sit on a grid 12 columns wide, and each one gets a grip in its header and a **⋯** (Tile options) button.

- **Move**: drag the tile by its header. It snaps to the grid as you go, a dashed outline shows where it will land, and the tiles in its way move down to make room; then everything moves up to close any gaps. Dragging down past a shorter tile, the two swap as soon as the dragged tile passes the middle of the one below.
- Drag near the top or bottom edge of the window to scroll the page while you drag; the tile stays under the pointer. With **Reduce motion** turned on in your system settings, the page scrolls at a steady, slower pace.
- **Resize**: pull the tile's right edge (width), bottom edge (height) or bottom-right corner (both). A tile is 1 to 12 columns wide and 1 to 8 rows tall.
- Press **Escape** while dragging to put the tile back where it was.

![A dashboard in Edit layout while the Usage by plan tile is dragged next to Active customers: a dashed outline shows where it will land, and the Save layout and Discard changes buttons are at the top](https://www.apitraffic.io/docs/images/reports/dashboard-drag.png)

Dragging works with a mouse, a pen or touch on a wide screen. On narrower screens the tiles stack in one or two columns, so use the menu or the keyboard instead.

### Without dragging

Nothing needs dragging. The **⋯** menu on each tile has **Move left**, **Move right**, **Move up**, **Move down**, **Wider**, **Narrower**, **Taller**, **Shorter** and **Remove from dashboard** (the report itself is kept). Moving a tile onto its neighbour swaps the two: up or down past the tile above or below, and left or right past the tile beside it in the same row.

![The Tile options menu of the Top customers tile, open, with Move left, Move right, Move up, Move down, Wider, Narrower, Taller, Shorter and Remove from dashboard](https://www.apitraffic.io/docs/images/reports/dashboard-tile-menu.png)

Or press **Tab** to reach a tile, then:

| Keys | Action |
|---|---|
| Arrow keys | Move the tile one column or row |
| Shift + Left / Right | Make the tile one column narrower or wider |
| Shift + Up / Down | Make the tile one row shorter or taller |

Each change is announced to screen readers, for example "Top customers moved to column 5, row 1, 8 wide by 4 tall."

When you have changed the layout, the **Done arranging** button becomes **Save layout**: click it to save and finish. **Discard changes** puts back what was saved. Leaving the page with unsaved changes asks first.

## Sharing

A dashboard is **Only me** (private) or **Everyone in the account**. Click **Details** to change its name, description or who can see it. Only a shared dashboard's owner can make it private again: for an admin editing someone else's dashboard, **Only me** is disabled. A shared dashboard cannot filter on a tag classified **Personal**; the API refuses to save it and suggests **Only me**.

- A shared dashboard can only show reports that are shared too, so everyone who opens it can see every tile. While you arrange a shared dashboard, **Add a saved report** offers shared reports only.
- The owner can change or delete a dashboard. Owners and admins can also change or delete any shared dashboard. Everyone else sees it as **View only**.
- Your plan may limit how many dashboards you can create. When you reach the limit, **New dashboard** says so and links to the plans.

**Delete** removes the dashboard for everyone, after you confirm. Its reports are kept.

### Embedding a dashboard in your app

A shared dashboard can be shown inside your own product, filtered to each of your customers: click **Embed** and turn on **Allow embedding** (account owners and admins). Making the dashboard private turns embedding off. See [Embedded Reports and Dashboards](https://www.apitraffic.io/docs/integrations/embed-reports).

## Troubleshooting

**A tile says it could not run.** Click **Try again**. If the query timed out, shorten the dashboard's time range or add a filter.

**This dashboard filters on a personal tag you can't view, so its tiles can't run for you.** The dashboard's filter uses a tag classified **Personal** that your role may not see. It is not shown, you cannot edit it, and the tiles are not run for you: running them without it would show numbers the filter is meant to narrow, so the API refuses them. Your other changes (time range, scope, layout) still save without touching it. If you can edit the dashboard, click **Remove this filter** in the notice: after you confirm, the filter is deleted for everyone and is lost (you can't see it to put it back), and the tiles run without it. Otherwise, ask someone who can view personal tags.

**A tile says No requests matched.** Nothing matched both the report's own filter and the dashboard filter. Check **Filter every tile**.

**A tile says its report was deleted or is no longer shared with you.** Click **Remove tile**, or ask the report's owner to share it again.

**I can't add a report.** The dashboard is shared and the report is private. Share the report first, from its **Save** dialog.

**Save is missing.** You can't edit this dashboard. Your changes to the filter still apply while you are on the page.

For the REST API, see [Reports API](https://www.apitraffic.io/docs/api-reference/reports#dashboards).