# How do I track KPIs on a Shorter Loop dashboard?

KPIs are the numbered tiles at the top of a dashboard. Each one tracks a single metric over time: a current value, an optional target, and a history you can chart.

---

## What are the two tile states?

### What does an empty tile look like?

![Empty KPI tile](https://cdn.shorterloop.com/docs/kpi-tile-empty.png)

A dashed border, **"Your trend starts here / Add your first value to watch it grow"**, and two actions:

| Action | What it does |
|---|---|
| **Enter value** | Opens the metric editor so you can type a number |
| **+ Connect** | Opens the connect / API reference panel for wiring up a data source |

### What does a live tile show?

![Live KPI tile](https://cdn.shorterloop.com/docs/kpi-tile-live.png)

| Element | Meaning |
|---|---|
| **KPI-7** | The KPI's unique ID. Click it to open the connect / API reference |
| **108 %** | Current value and unit |
| **↗ +2 vs prev** | Change since the previous recorded value. Green ↗ up, red ↘ down |
| **Sparkline** | The trend, once there are at least three values |

Hovering a tile reveals its actions:

| Icon | Action |
|---|---|
| ✎ | **Edit** the metric |
| 🔗 | **Connect** — opens the API / source panel |
| ✕ | **Delete** the metric |

---

## What does a fully populated dashboard look like?

![Dashboard with live and empty KPIs](https://cdn.shorterloop.com/docs/picked-dashboard-live.png)

The **2/5 live** badge in the header counts how many tiles actually have data.

---

## How do I add a KPI?

Click the **+ Add a KPI** tile at the end of the grid ("Track another metric that matters"), or **+ Add KPI** in the empty-dashboard state.

![Add a KPI](https://cdn.shorterloop.com/docs/kpi-add-dialog.png)

---

## How do I enter or edit a value?

**Enter value** (or the ✎ icon) opens the metric editor.

![Metric editor](https://cdn.shorterloop.com/docs/kpi-edit-dialog.png)

| Field | Notes |
|---|---|
| **Title** | Required, up to 255 characters |
| **KPI Unique ID** | Read-only, with a copy button. Use it in API calls |
| **Unit** | Free text up to 12 characters — `%`, `$`, `days`, `pts/wk` … |
| **Benchmark** | Your target value |
| **or more / or less** | Which direction is good. *or more* → higher is better; *or less* → lower is better |
| **Time visualization** | Turn on to render this metric as a chart |
| **Add to dashboard** | Whether the metric appears on the dashboard (shown only when editing from outside the dashboard) |
| **Due date** | Optional deadline for hitting the benchmark |
| **Current value** | The new reading. Each save adds a point to the history |
| **Revision list** | Every past value with its timestamp. Editing one shows **Confirm changes** with **Ignore** / **Confirm** |
| **🗑 (header)** | Deletes the whole metric |
| **CSV / JSON** | Bulk-import a series of values |

Press **Save** to record the value.

### How many values do I need before a trend appears?

Each save adds one data point. The tile's sparkline and the full chart need **at least three** data points — until then the KPI widget shows *"Not enough data points for a graph (Required minimum 3)"*.

---

## How do I see a chart?

Click a tile's sparkline to open a large trend preview.

![Chart preview](https://cdn.shorterloop.com/docs/kpi-chart-preview.png)

In the **KPI metrics** widget you can also toggle between a line chart and a bar chart with the small chart icon.

Trend arrows next to the current value compare the two most recent readings: ↑ trending up, ↓ trending down, – no change.

---

## How do benchmarks and status indicators work?

When a benchmark is set, the tile shows **Current** and **Target** side by side, plus *or MORE* / *or LESS*.

| Situation | Indicator |
|---|---|
| Current equals the benchmark | ✓ tick |
| Current is past a *or less* benchmark | ⚠ alert |
| *or more* metric with a value | Value shown in the success colour |
| *or less* metric with a value | Value shown in the warning colour |

---

## Can I feed KPIs from my own systems?

Clicking **+ Connect** or a tile's KPI ID opens a reference panel with a ready-made API recipe for pushing values in.

![KPI API reference](https://cdn.shorterloop.com/docs/kpi-api-reference.png)

It includes:

- the endpoint — `POST /api/initiatives/{initiativeId}/kpi`
- required request headers (`x-api-key: Bearer <token>`, `Content-Type: application/json`)
- a complete request-body example with your KPI's actual title, benchmark, unit, and due date filled in
- a copy-paste JavaScript `fetch` example
- notes — including how to attach a KPI to a backlog work item using `artifact` and `artifactExternalKey`

For pulling values from a third-party tool instead, see [11 · Connecting data sources](https://help.shorterloop.com/how-do-i-connect-a-data-source-to-a-kpi-or-tile).

---

## How do I reorder KPIs?

Enter **Edit layout** and drag tiles by their handle. See [09 · Editing the layout](https://help.shorterloop.com/how-do-i-rearrange-my-dashboard-layout).

---

## How do I delete a KPI?

Use the ✕ on the tile, or the 🗑 in the metric editor's header. This removes the metric and its history.