references/models-annotations.md
Annotations
Annotation (system.annotations)
Annotations are timestamped notes used to mark product changes, incidents, or releases directly on charts.
Columns
Column | Type | Nullable | Description
--- | --- | --- | ---
id | Integer | NOT NULL | Annotation id.
team_id | Integer | NOT NULL |
content | String | NULL | Annotation text.
scope | String | NOT NULL | Where the annotation applies: 'project', 'organization', 'dashboard', 'dashboard_item' (insight), or 'recording'.
creation_type | String | NOT NULL | How the annotation was created, e.g. user-created vs GitHub.
date_marker | DateTime | NULL | The point in time the annotation marks on a chart.
deleted | Integer | NOT NULL | 1 if the annotation has been deleted, 0 otherwise.
dashboard_item_id | Integer | NULL | Insight this annotation is scoped to; joins to insights.id.
dashboard_id | Integer | NULL | Dashboard this annotation is scoped to; joins to dashboards.id.
created_by_id | Integer | NULL | User who created the annotation.
created_at | DateTime | NULL | When the annotation was created.
updated_at | DateTime | NOT NULL | When the annotation was last updated.
Key Relationships
- Insights:
dashboard_item_id->system.insights.id - Dashboards:
dashboard_id->system.dashboards.id
Important Notes
- The API usually hides
deleted=truerows; SQL queries should filter them explicitly when needed. scope='organization'annotations can appear across multiple projects in the same organization.
Common Query Patterns
List recent non-deleted annotations:
SELECT id, scope, content, date_marker, created_at
FROM system.annotations
WHERE NOT deleted
ORDER BY date_marker DESC NULLS LAST
LIMIT 100
Find annotations around a release window:
SELECT id, content, scope, date_marker
FROM system.annotations
WHERE NOT deleted
AND date_marker >= toDateTime('2026-03-01 00:00:00')
AND date_marker < toDateTime('2026-03-08 00:00:00')
ORDER BY date_marker ASC
Get organization-scoped annotations only:
SELECT id, content, date_marker, created_by_id
FROM system.annotations
WHERE NOT deleted
AND scope = 'organization'
ORDER BY date_marker DESC NULLS LAST