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

# Boards & Dashboards

> Build dashboards with metric blocks, notes, and grid layout to visualize your analytics.

Boards are your team's dashboards. Each board holds metric blocks that visualize your data — active users, event counts, sessions, log volume — alongside markdown notes for context and commentary.

## Creating a board

Create a board from the API, the TUI, or through an AI assistant via [MCP](/tools/mcp):

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/boards \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"title": "Product Overview"}'
```

Give it a descriptive title. Your team will scan board titles when deciding where to look.

## Metric blocks

Each board is made up of blocks. A **metric block** displays a chart, number, or table powered by a Tell query. You can have up to 50 metric blocks per board, each with up to 20 data series.

Typical blocks:

* **DAU/WAU/MAU** — active user trends over 30 or 90 days
* **Top events** — most frequent events ranked by count
* **Conversion metrics** — custom aggregations like sum of `purchase.amount`
* **Log volume** — error rate or log count by level over time
* **Treemap** — [grouped metrics](/analytics/events#grouped-metrics) showing proportional composition with size and intensity
* **Funnel** — step-by-step [conversion analysis](/analytics/funnels)
* **Retention** — [cohort retention](/analytics/retention) matrix

## Note blocks

**Note blocks** hold markdown text. Use them for context: explain why a metric matters, note a recent deploy, or link to related resources. Up to 50 note blocks per board.

## Pinning boards

Pin a board to keep it at the top of your workspace's board list. Pinned boards are what your team sees first — use them for the dashboards everyone checks daily.

```bash theme={null}
curl -X PUT https://your-tell-server/api/v1/boards/{board-id}/pin \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'
```

## Sharing boards

Share a board with anyone via a public URL — no login required. This is useful for embedding in wikis or sending to stakeholders who don't have Tell accounts.

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/boards/{board-id}/share \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

The response includes a URL like `https://your-tell-server/s/b/a1b2c3d4`. Revoke the link at any time to cut off access.

See [Sharing](/api/sharing) for the full API reference.

## Saved metrics

If you find yourself building the same metric block on multiple boards, save it. Saved metrics store the query configuration so you can reuse it or share it independently.

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/metrics/saved \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Active Users",
    "workspace_id": "ws_abc123",
    "query": { "metric": "wau", "range": "30d", "granularity": "daily" }
  }'
```

Saved metrics can also be shared via public links, just like boards.

## Marks

Marks are timeline annotations that overlay on your charts. Use them to record deploys, incidents, launches, or any event that might explain a change in your metrics. When you see a spike or dip, marks tell you what happened.

### Create a mark

From the CLI:

```bash theme={null}
# Mark a release
tell mark "Shipped v2.1.0"

# Mark an incident with a specific time
tell mark "Payments down" -c incident --at 2025-06-15T23:47:00Z

# Mark with a description and reference URL
tell mark "Series A announced" -c news -d "Blog post went live" --source_ref https://blog.example.com/series-a
```

Via the API:

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/marks \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Shipped v2.1.0",
    "category": "release",
    "source_ref": "https://github.com/example/repo/releases/tag/v2.1.0"
  }'
```

### Categories

| Category   | When to use                                        |
| ---------- | -------------------------------------------------- |
| `release`  | Deploys, version bumps, feature launches (default) |
| `news`     | Blog posts, announcements, funding rounds          |
| `incident` | Outages, degradations, on-call events              |

### Scope

Marks are **public** by default — visible to everyone in the workspace. Set a mark to **private** and only you can see it:

```bash theme={null}
tell mark "Testing hypothesis" --private
```

### List and filter marks

```bash theme={null}
# List marks from the last 90 days
tell mark list

# Filter by category and time
tell mark list --last 30d -c release
```

### Delete a mark

```bash theme={null}
tell mark delete <mark-id>
```

Only the mark creator or a workspace admin can delete marks.

See the [marks API reference](/api/queries#marks) for full endpoint documentation.

## Who can do what

| Action                    | Role           |
| ------------------------- | -------------- |
| View boards               | Viewer         |
| Create boards             | Editor         |
| Edit or delete own boards | Editor         |
| Edit or delete any board  | Admin          |
| Share boards              | Owner or Admin |
| Create marks              | Editor         |
| Delete own marks          | Editor         |
| Delete any mark           | Admin          |

## What's next

* [Boards & Metrics API](/api/boards) — full API reference
* [Data Queries](/api/queries) — the metrics that power board blocks
* [Segments](/analytics/segments) — filter analytics by user segments