Skip to main content
Annotations provide a way to mark points in time or time ranges on graphs with rich events from data sources or manual entries. They help correlate metrics with events like deployments, incidents, or business milestones.

​
What are Annotations?

Annotations appear as vertical lines or shaded regions on graphs, with associated metadata such as:
  • Title and text: Descriptive information about the event
  • Tags: Categorize and filter annotations
  • Time range: Either a single point in time or a time region
  • Source: Manual entries, alert state changes, or data source queries
Annotations are displayed across all panels in a dashboard that support them, making it easy to correlate events across different metrics.

​
Creating Manual Annotations

You can create annotations directly from the dashboard UI:
  1. Ctrl+Click (or Cmd+Click on Mac) on a graph panel at the desired time
  2. Fill in the annotation details:
    • Tags: Add searchable tags
    • Description: Event details
    • Time range: Optionally drag to create a region annotation
  3. Save the annotation

​
Using the API

Create annotations programmatically via the HTTP API: 
interface AnnotationEvent {
  id?: string;
  dashboardId?: number;
  dashboardUID?: string | null;
  panelId?: number;
  userId?: number;
  time?: number;          // Unix timestamp in milliseconds
  timeEnd?: number;       // For region annotations
  isRegion?: boolean;
  title?: string;
  text?: string;
  tags?: string[];
  color?: string;
}

curl -X POST \
  'http://localhost:3000/api/annotations' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": 1678886400000,
    "timeEnd": 1678890000000,
    "tags": ["deployment", "backend"],
    "text": "v2.0 deployment completed",
    "isRegion": true
  }'

​
Annotation Queries

Annotation queries automatically fetch events from data sources and display them on dashboards.

​
Configuring Annotation Queries

  1. Go to Dashboard Settings → Annotations
  2. Click Add annotation query
  3. Configure the query:
    • Name: Display name for the annotation layer
    • Data source: Select the source (e.g., Prometheus, Loki, built-in)
    • Query: Define the query using the data source’s query language
    • Field mappings: Map data source fields to annotation properties

​
Built-in Grafana Annotations

The built-in Grafana data source provides access to:
  • Annotations: Manual annotations stored in Grafana’s database
  • Alert state history: Automatic annotations from alert state changes
interface AnnotationQuery {
  datasource: DataSourceRef;
  enable: boolean;
  hide?: boolean;
  iconColor: string;
  name: string;
  target?: AnnotationTarget;
  type?: string;
}

​
Example: Prometheus Annotation Query

Query Prometheus for deployment events: 
CHANGES(deployment_version[5m]) > 0

​
Field Mapping

Map data source fields to annotation properties: 
interface AnnotationEventFieldMapping {
  source?: 'field' | 'text' | 'skip';
  value?: string;      // Field name or constant text
  regex?: string;      // Optional regex transform
}

type AnnotationEventMappings = Partial<Record<keyof AnnotationEvent, AnnotationEventFieldMapping>>;
Example mapping: 
{
  "time": { "source": "field", "value": "timestamp" },
  "title": { "source": "field", "value": "event_name" },
  "text": { "source": "field", "value": "description" },
  "tags": { "source": "field", "value": "labels" }
}

​
Displaying Annotations

​
Dashboard-wide Annotations

Annotations configured in dashboard settings appear on all compatible panels: 
interface AnnotationContainer {
  list: AnnotationQuery[];
}

​
Panel-specific Filtering

Filter which annotations appear on specific panels: 
interface AnnotationPanelFilter {
  exclude?: boolean;
  ids: number[];
}

​
Visual Customization

  • Color: Set per annotation query or individual annotation
  • Tags: Filter displayed annotations by tag
  • Visibility: Toggle annotation layers on/off

​
Querying Annotations

Retrieve annotations programmatically: 
curl 'http://localhost:3000/api/annotations?from=1678886400000&to=1678972800000'
Response structure: 
interface AnnotationTag {
  tag: string;
  count: number;
}

interface AnnotationTagsResponse {
  result: {
    tags: AnnotationTag[];
  };
}

​
Alert State History

Grafana automatically creates annotations when alert rules change state: 
// Query alert-specific annotations
interface AlertAnnotationQuery {
  alertUID: string;
}

curl 'http://localhost:3000/api/annotations?alertUID=alert-uid-123'
These annotations include:
  • Alert name and state transition
  • Timestamp of state change
  • Alert labels as tags
  • Automatically color-coded by severity

​
TypeScript Client Example

Using the annotation API client from public/app/features/annotations/api.ts:1: 
import { annotationServer } from 'app/features/annotations/api';
import { AnnotationEvent } from '@grafana/data';

const server = annotationServer();

// Save an annotation
const annotation: AnnotationEvent = {
  time: Date.now(),
  tags: ['deployment'],
  text: 'Production deployment',
};

await server.save(annotation);

// Update an annotation
const updated = { ...annotation, id: '123', text: 'Updated text' };
await server.update(updated);

// Delete an annotation
await server.delete({ id: '123' });

// Get tags
const tags = await server.tags();
// Returns: [{ term: 'deployment', count: 15 }, ...]

​
Best Practices

Establish a tagging convention across your team:
  • Type: deployment, incident, maintenance
  • Environment: production, staging, dev
  • Team: backend, frontend, data
This makes annotations easier to filter and search.
Integrate annotation creation into deployment pipelines:
# In your deployment script
curl -X POST "$GRAFANA_URL/api/annotations" \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -d '{
    "tags": ["deployment", "'$ENVIRONMENT'"],
    "text": "Deployed '$VERSION' to '$ENVIRONMENT'"
  }'
Use region annotations (with timeEnd) to mark incident duration:
  • Start time: When the incident began
  • End time: When it was resolved
  • Tags: Severity level, affected services
Too many annotation queries can slow down dashboard loading:
  • Keep to 3-5 annotation queries per dashboard
  • Use specific filters in queries
  • Disable queries when not needed

Dashboard Settings

Configure dashboard-wide annotation queries

Alerting

Automatic annotations from alert state changes

Data Sources

Annotation support varies by data source

API Reference

Complete HTTP API documentation