Skip to main content
Returns an array of Annotation objects for the specified indicator, in the order they are stored in the database.

​
Path parameters

​
indicator_id
string
required
The indicator’s unique identifier. Must be a valid MongoDB ObjectId (24-character hex string).

​
Response

Returns an array of Annotation objects. An empty array is returned when no annotations exist.
​
id
string
Unique identifier of the annotation (MongoDB ObjectId).
​
indicator_id
string
required
The ObjectId of the indicator this annotation belongs to.
​
type
string
required
Axis the annotation is drawn on. One of:
  • xaxis — a vertical line at a specific x value (typically a datetime)
  • yaxis — a horizontal line at a specific y value
​
value
string | number
required
The position of the annotation line.
  • For xaxis annotations: an ISO 8601 datetime string (e.g., "2024-06-01T00:00:00").
  • For yaxis annotations: a numeric value (e.g., 1500.0).
​
label
string
required
Human-readable label displayed next to the annotation line on the chart.
​
color
string
required
CSS hex color of the annotation line (e.g., "#FF5733"). Defaults to "#000000".
​
stroke_dasharray
integer
required
Dash pattern for the annotation line. 0 renders a solid line. Positive integers set the dash length in pixels.
​
opacity
number
required
Opacity of the annotation line, from 0.0 (transparent) to 1.0 (fully opaque). Defaults to 1.0.

​
Error responses

StatusDescription
400 Bad Requestindicator_id is not a valid ObjectId.

​
Examples

curl -X GET \
  "https://api.example.com/indicators/64b1f2c3d4e5f6a7b8c9d0e1/annotations" \
  -H "Accept: application/json"

​
Example response

200
[
  {
    "id": "64c2f3a1b5e6d7f8e9a0b1c2",
    "indicator_id": "64b1f2c3d4e5f6a7b8c9d0e1",
    "type": "xaxis",
    "value": "2020-03-11T00:00:00",
    "label": "COVID-19 declared pandemic",
    "color": "#E74C3C",
    "stroke_dasharray": 4,
    "opacity": 0.8
  },
  {
    "id": "64c2f3a1b5e6d7f8e9a0b1c3",
    "indicator_id": "64b1f2c3d4e5f6a7b8c9d0e1",
    "type": "yaxis",
    "value": 2000.0,
    "label": "Baseline target",
    "color": "#2ECC71",
    "stroke_dasharray": 0,
    "opacity": 1.0
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us