Annotations

Annotations are vertical markers on time-series charts — used to label deploys, incidents, marketing pushes, or any external event you want correlated with your metrics. They appear on Trends, Funnels, and Retention charts.

Open Annotations in the sidebar (/annotations).

Adding an annotation

You have three ways to create one:

1. From a chart

Hover over the chart at the date you want. A small ＋ appears on the X-axis tooltip — click it to open the annotation drawer pre-filled with that date.

2. From the Annotations page

Click New annotation. Fields:

Field	Notes
Date	Required. The marker position on the timeline.
Label	Short text shown on the chart.
Description	Optional long form, visible in hover/drawer.
Scope	`workspace` (visible on every chart) or `query` (only on a specific saved query).
Color	One of six preset colors.

3. Via webhook (deploys, incidents)

Wire deploys or PagerDuty incidents to the annotation webhook so they appear automatically:

curl -X POST https://api.trackcrumb.com/api/v1/annotations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Deploy v2.4.1","date":"2026-05-12T14:00:00Z","color":"emerald","scope":"workspace"}'

⚠️

The webhook is rate-limited per workspace to prevent runaway deploy systems from flooding charts. Failed calls return 429 — retry with backoff.

Managing annotations

The list view paginates 20 per page. Checkboxes enable bulk delete. The Export CSV button downloads every annotation in the current scope with columns: date, label, description, color, scope, created_by, created_at.

Annotation panels on insights

Open any Trend or Funnel and the right-hand drawer shows the annotations falling within the chart’s date range. Click an annotation to jump to its date on the chart.

Limits & gotchas

Label length — 1–120 chars.
query-scoped annotations only show on that one saved query’s chart, not on ad-hoc reports.
Deleting an annotation is immediate — no soft-delete or undo.

Alerts — automatic alerts on metric anomalies
Saved queries — scope annotations to a specific query

Experiments Alerts