Boards & Dashboards

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:

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 showing proportional composition with size and intensity
Funnel — step-by-step conversion analysis
Retention — cohort 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.

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}'

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.

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 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.

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:

# 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:

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"
  }'

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:

tell mark "Testing hypothesis" --private

List and filter marks

# 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

tell mark delete <mark-id>

Only the mark creator or a workspace admin can delete marks. See the marks API reference 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 — full API reference
Data Queries — the metrics that power board blocks
Segments — filter analytics by user segments

Getting Started

Tracking

Pipeline

Analytics

Installing

Boards & Dashboards

Creating a board

Metric blocks

Note blocks

Pinning boards

Saved metrics

Marks

Create a mark

Categories

Scope

List and filter marks

Delete a mark

Who can do what

What’s next

​Creating a board

​Metric blocks

​Note blocks

​Pinning boards

​Sharing boards

​Saved metrics

​Marks

​Create a mark

​Categories

​Scope

​List and filter marks

​Delete a mark

​Who can do what

​What’s next

Creating a board

Metric blocks

Note blocks

Pinning boards

Sharing boards

Saved metrics

Marks

Create a mark

Categories

Scope

List and filter marks

Delete a mark

Who can do what

What’s next