​

Dashboard service overview

The Dashboard service API manages Coralogix dashboards: it lets you create, retrieve, update, delete, and organize dashboards, pin them to favorites, and look up a catalog of every dashboard the caller can see. A dashboard is a JSON payload describing a Layout of Sections, each containing Rows of Widgets, parameterized by Variables and annotated with Annotations. The same payload is consumed by Create and Replace operations and returned by Get. This overview describes:

• The 10 endpoints exposed by the Dashboards service (CRUD + pinning + slug lookup + folder assignment + catalog).
• The structure of the dashboard payload (Dashboard message and its components).
• The widget, variable, filter, annotation, and action types that compose a dashboard.

For user-facing concept introductions and step-by-step tutorials, see the Custom Dashboards user guide.

​

Authentication and permissions

To use the Dashboard service API you need to create a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add the following individual permissions.

​

Common error response codes

​

Endpoints

​

Dashboards (CRUD, pinning, slug, folder assignment)

​

Dashboard catalog

The catalog endpoint mirrors the Manage dashboard catalog tutorial on the user-guide side. For folder operations (list, get, create, replace, delete), see the Dashboard folders service.

​

Dashboard payload

The Dashboard message is the unit accepted by Create / Replace and returned by Get. Required fields: name and layout. All other fields are optional. For broader product context, see Manage dashboard settings.

​

Layout

A Layout is an ordered list of Sections. Each Section contains an ordered list of Rows, and each Row contains an ordered list of Widgets. The hierarchy is fixed at three levels: Layout → Section → Row → Widget. For the user-facing concept and UI walkthrough, see the Sections tutorial.

​

Section

CustomSectionOptions carries: name, description, collapsed (boolean), color (a SectionPredefinedColor enum: cyan / green / blue / purple / magenta / pink / orange), and optionally a repetitive_var (a variable name that turns the section into a repeating block — one rendered copy per selected value of that variable).

​

Row

​

Widgets

A Widget carries either a definition (an inline widget configuration) or a reference (a WidgetReference pointing at a widget defined on another dashboard). The two are mutually exclusive — the backend rejects payloads that set both or neither. For user-facing widget creation walkthroughs, see Add monitoring data to widgets and the getting-started guide.

​

Cross-dashboard widget reuse

A WidgetReference re-renders a widget defined on a different dashboard: Use a reference when you want a widget to appear on multiple dashboards without copying its definition; updates to the source widget propagate to every dashboard that references it.

​

Widget catalog

Each widget’s definition is a oneof over the variants below. Every chart accepts a query over one of four data sources — Logs (Lucene), Spans (Lucene), Metrics (PromQL), or DataPrime — except Markdown, which carries no query. For the full field set per widget (color schemes, legend, axis bounds, units, etc.), see the corresponding schema in openapi_v5.yaml.

​

Variables (V1, deprecated)

The Dashboard.variables field uses the V1 variable model (proto package variables). It is deprecated; new dashboards should populate variables_v2 instead (see Variables (V2)). For user-facing variable concepts and UI walkthroughs, see Create and manage variables. A V1 Variable has name, optional display_name / description, a display_type (VariableDisplayType enum), and a Definition. The Definition.value is a oneof over:

• Constant — (deprecated within V1) a single fixed value.
• MultiSelect — a value selected from a list, sourced from one of: a logs path (LogsPathSource), a metric label (MetricLabelSource), a constant list (ConstantListSource), a span field (SpanFieldSource), or an arbitrary query (QuerySource). Supports selection (single or multi-value), an OrderDirection, and VariableSelectionOptions.

V1 schemas remain in the spec for backward compatibility with existing dashboards. The MultiSelect.selected field within V1 is also marked deprecated — current dashboards encode the user’s selection through VariableSelectionOptions and the consuming UI.

​

Variables (V2)

Variables let a dashboard accept user-supplied or query-derived values that are substituted into widget queries at view time. The dashboard payload carries the V2 variable model (proto package com.coralogixapis.dashboards.v1.ast.variables_v2); the older V1 model (Variable / Variable.Definition / VariableDefinitionConstant / VariableDefinitionMultiSelect) is still present in the spec for backward compatibility — see Variables (V1, deprecated). A VariableV2 carries: a unique id (UUID), name, optional display_name and description, a display_type (VariableDisplayTypeV2 enum — values in the collapsible below), a source that produces candidate values, a value selection, and a display_full_row toggle.

​

Source (VariableSourceV2)

A oneof over three variants:

• QuerySource — values come from a Coralogix query against logs, spans, metrics, or DataPrime. Carries a refresh_strategy, value_display_options (label/value regex), and an all_option.
• StaticSource — values are an inline list (with an all_option).
• TextboxSource — value is free-form text entered in the dashboard UI.

QuerySource has four sub-variants matching its data source: LogsQuery, SpansQuery, MetricsQuery, DataprimeQuery (openapi schema names: VariableSourceV2QuerySourceLogsQuery, …SpansQuery, …MetricsQuery, …DataprimeQuery).

​

Value (VariableValueV2)

A oneof over six variants (proto names):

• SingleStringValue
• SingleNumericValue
• MultiStringValue — wraps either an AllValue, a ListValue, or a SelectedAllValue
• LuceneQueryValue
• RegexValue
• IntervalValue

For the full message structure, see the VariableV2, VariableSourceV2.*, VariableValueV2.*, and VariableDisplayTypeV2 schemas in openapi_v5.yaml. For user-facing variable usage, see Create and manage variables.

​

Filters

A Filter constrains the data that widgets render. Each filter has: Filter.WidgetScope is a oneof over:

• AllWidgets — the filter applies to every widget on the dashboard.
• SpecificWidgets — the filter applies only to the listed widget_ids.

Each Source variant carries source-appropriate fields (e.g., LogsFilter carries field, operator, and observation_field). For the full per-source field list, see the Filter.LogsFilter, Filter.SpansFilter, and Filter.MetricsFilter schemas in openapi_v5.yaml.

​

Annotations

Annotations mark significant events on dashboard widgets — for example, deploys, incidents, or business milestones — so they appear as overlays on charts that match their scope. An annotation is sourced from a Coralogix query, manual input, or a recurring event, and can be scoped to all widgets on the dashboard or a specific set. For user-facing concept and creation walkthrough, see Create annotations. An Annotation message has:

• id — unique identifier
• name — display name
• description — optional description
• enabled — boolean toggle
• source — where the events come from (see below)
• scope — which widgets the annotation overlays
• color — an AnnotationColor enum value

​

Source (Annotation.Source)

A oneof over six source types:

• MetricsSource — events from a PromQL query (promql_query). Carries a Strategy (currently StartTimeMetric — uses the first data point’s value as the annotation timestamp), a message_template, label list, AnnotationOrientation, and an IntervalResolution.
• LogsSource — events from a Lucene logs query (lucene_query). The strategy is a oneof over Instant (single timestamp field), Range (start + end timestamp fields), and Duration (start timestamp + duration field). Supports label_fields and DataModeType.
• SpansSource — same shape as LogsSource but over spans.
• DataprimeSource — events from a DataPrime query (query) with the same Instant/Range/Duration strategy variants.
• ManualSource — manually configured events with an Instant (single value + Unit) or Range (start_value / end_value + Unit) strategy. Optional custom_unit, message_template, and AnnotationOrientation.
• EventRecurrenceSource — events from a recurring schedule. Currently only WeeklyRecurrence (with selectable days_of_week from a Weekday enum) is supported, paired with an Instant (start hour) or Duration (start hour + length) strategy.

​

Scope — Annotation.WidgetScope (v5 only)

Annotation.WidgetScope is a oneof over:

• AllWidgets — annotation overlays every widget on the dashboard.
• SpecificWidgets — annotation overlays only the listed widget_ids.

Earlier spec versions (v3, v4) do not scope annotations to specific widgets — that surface is v5-only. (A separate top-level WidgetScope family exists in v3 and v4 for Filter scoping; it’s unrelated to annotations.)

​

Events (AnnotationEvent)

When the dashboard renders an annotation, each emitted event is either:

• Instant — a point in time with timestamp, labels, and payload.
• Range — a span with start, end, labels, and payload.

​

Related types

• AnnotationColor (enum) — color the annotation renders with.
• AnnotationOrientation (enum) — vertical / horizontal placement for metrics-sourced annotations.

​

Widget-side: filtering an annotation’s series

AnnotationSeriesVisibility is not part of the Annotation message — it’s defined alongside the widget-level SeriesVisibility schema. It’s an entry inside a widget’s SeriesVisibility.annotation_series list, with annotation_id, a SeriesVisibilityMode (HIDE_ALL / SHOW_ONLY), and a series_names list. Use it on the widget side to control which series of an already-defined annotation render on that widget. For the full message structure, see the Annotation and Annotation.Source.* schema families in openapi_v5.yaml.

​

Time frame

The dashboard’s time frame is a oneof:

• absolute_time_frame — a TimeFrame with from and to protobuf Timestamps. Fixed start and end times.
• relative_time_frame — a google.protobuf.Duration interpreted as an offset from “now.”

A dashboard-level time frame applies to every widget by default. Individual widgets (for example, the Dynamic widget) can override the dashboard time frame on a per-widget basis. For the user-facing time-interval picker UI, see Configure time interval.

​

Actions

The dashboard payload carries actions as a list of DashboardAction — publicly available actions a viewer can trigger from a dashboard or one of its widgets. The Custom URL template supports variable substitution: any {{variable_name}} in the URL is replaced with the matching variable’s resolved value when the user clicks the action.

Note: A separate, older Action message exists in the spec but is marked deprecated. The proto file describes it as “Unused dormant model that was part of plans of the product team, however it is now on hold. Recommended to not use this model or rely on it in any way.” Always use DashboardAction for the Dashboard.actions field.

​

Constants

This service references a number of enum types across query, display, variable, and identity schemas. For the full value list of each enum, see #/components/schemas/<EnumName> in openapi_v5.yaml. Notable enums:

• Query and data source: ActionDataSourceType, DataModeType, LogSeverityLevel, PromQLQueryType, SpanRelationType, MetricField, MetricAggregationType, DimensionField, DimensionAggregationType, MetadataField, DatasetScope, MetricsQueryEditorMode, Aggregation, AggregationType, SortByType, OrderDirection.
• Display and layout: VariableDisplayType, RefreshStrategy, SelectionType, TooltipType, StackedLine, RowStyle, BarValueDisplay, LabelSource, ScaleType, LegendColumn, LegendPlacement, LegendBy, Unit, ThresholdBy, ThresholdType, SectionPredefinedColor.
• Identity: TokenOriginType.