Skip to main content
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}'

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

​
Categories

CategoryWhen to use
releaseDeploys, version bumps, feature launches (default)
newsBlog posts, announcements, funding rounds
incidentOutages, 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

ActionRole
View boardsViewer
Create boardsEditor
Edit or delete own boardsEditor
Edit or delete any boardAdmin
Share boardsOwner or Admin
Create marksEditor
Delete own marksEditor
Delete any markAdmin

​
What’s next