Annotations API

Data is powerful; data with context is actionable. The Annotations feature in Cloud Analytics closes the gap between your charts and the real-world events that shape them. You can create Annotations directly on your reports, ensuring everyone who sees the data gets the full story. Annotations enable you to attach human context to time series and tabular data in DoiT Cloud Intelligence. Typical use cases include marking infrastructure changes, business events, cost anomalies, or experiments so that FinOps and engineering teams can correlate spend and performance with real-world events.

Required permissions

• To create annotations, your API key must belong to a user with the Cloud Analytics Admin permission.
• To edit an annotation, your API key must belong to the annotation owner or a user with the Editor permission.
• To delete an annotation, your API key must belong to the annotation owner or a user with the Cloud Analytics Admin permission.
• For details, see Roles and permissions in the DoiT Help Center.

Operations

• [GET /analytics/v1/annotations](ref:listannotations) Lists annotations.
• [GET /analytics/v1/annotations/{id}](ref:getannotation) Retrieves a single annotation.
• [POST /analytics/v1/annotations](ref:createannotation) Creates an annotation.
• [PATCH /analytics/v1/annotations/{id}](ref:updateannotation) Updates an annotation.
• [DELETE /analytics/v1/annotations/{id}](ref:deleteannotation) Deletes an annotation.

Schema

Annotation object

Responses from the Annotations API use the AnnotationListItem schema. At a high level, an annotation represents a dated note with optional labels that can be rendered on Cloud Analytics reports.

Below are the common properties you will see in annotation responses:

The full schema may include additional properties that control visibility and report targeting. Refer to the API Reference for the exact field list.

List response

GET /analytics/v1/annotations returns a paginated collection:

Examples

YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key as described in the Get Started section of the DoiT API docs. ([DoiT Cloud Intelligence][3])

All examples use curl with short options to avoid relying on any specific shell aliases.

List annotations

The listAnnotations operation returns annotations your account has access to, in reverse chronological order by default.

You can filter and sort the results using query parameters.

Query parameters

Filter expressions follow the standard DoiT API filter syntax: key:[<value>], with multiple filters combined using the pipe character. For example, to find annotations that mention “budget” and are tagged with a specific label, you can use something like content:budget|labels:special-event.

Sample request

curl -X GET \
  'https://api.doit.com/analytics/v1/annotations?maxResults=5' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'accept: application/json'

Sample response body

{
  "pageToken": "cG4weUwyS0t6UWRVQTV5Oabcdmc",
  "rowCount": 5,
  "annotations": [
    {
      "id": "bG1bRYQvDWEsEs2auQnE",
      "content": "synthesize",
      "timestamp": "2026-01-07T12:02:01.631Z",
      "reports": [
        "2fhAJPvPz950syFUh0Zw"
      ],
      "labels": [
        {
          "id": "utHqK0OmwbPy1au3Xy22",
          "name": "Monitoring"
        }
      ],
      "createTime": "2026-01-07T12:02:01.947239Z",
      "updateTime": "2026-01-07T12:02:01.947239Z"
    },
    {
      "id": "G6brQONzrFLyNCLcsceQ",
      "content": "Loan",
      "timestamp": "2026-01-07T11:30:49.829Z",
      "reports": [
        "2fhAJPvPz950syFUh0Zw"
      ],
      "labels": [
        {
          "id": "utHqK0OmwbPy1au3Xy22",
          "name": "Monitoring"
        }
      ],
      "createTime": "2026-01-07T11:30:50.427726Z",
      "updateTime": "2026-01-07T11:30:50.427726Z"
    },
   ...

Create an annotation

The createAnnotation operation creates a new annotation that can appear on eligible reports for the specified date.

At minimum, you must specify:

• content – the annotation text.
• timestamp – the date the annotation should attach to, in milliseconds since the epoch.

You can optionally include labels and visibility settings so that the annotation is only shown on specific reports or stays global. Exact visibility fields are defined in the API Reference; conceptually, they correspond to the “All reports” or “This report only” options in the console.

Sample request

curl -X POST \
  'https://api.doit.com/analytics/v1/annotations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "reports": [
    "HmqMNr1uIMQQySpiBWyt"
  ],
  "labels": [
    "utHqK0OmwbPy1au3Xy22"
  ],
  "content": "A test annotation",
  "timestamp": "2026-01-07T12:04:54.076Z"
}'

The structure of the visibility object and any additional fields (for example, to target specific reports) must follow the CreateAnnotationRequest schema in the API Reference.

Sample response body

On success, the API returns the created annotation object.

{
  "id": "Cveqe4ByUxfi3spIueGY",
  "content": "A test annotation",
  "timestamp": "2026-01-07T12:04:54.076Z",
  "reports": [
    "HmqMNr1uIMQQySpiBWyt"
  ],
  "labels": [
    {
      "id": "utHqK0OmwbPy1au3Xy22",
      "name": "Monitoring"
    }
  ],
  "createTime": "2026-01-07T12:36:30.58333Z",
  "updateTime": "2026-01-07T12:36:30.58333Z"
}

Retrieve an annotation

The getAnnotation operation returns a single annotation by ID.

Path parameter

Sample request

curl -X GET \
  'https://api.doit.com/analytics/v1/annotations/Cveqe4ByUxfi3spIueGY' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'accept: application/json'

Sample response body

{
  "id": "Cveqe4ByUxfi3spIueGY",
  "content": "A test annotation",
  "timestamp": "2026-01-07T12:04:54.076Z",
  "reports": [
    "HmqMNr1uIMQQySpiBWyt"
  ],
  "labels": [
    {
      "id": "utHqK0OmwbPy1au3Xy22",
      "name": "Monitoring"
    }
  ],
  "createTime": "2026-01-07T12:36:30.58333Z",
  "updateTime": "2026-01-07T12:36:30.58333Z"
}

Update an annotation

The updateAnnotation operation updates an existing annotation by ID. Use this to correct text, adjust the date, or change labels and visibility.

The request body follows the UpdateAnnotationRequest schema and typically allows partial updates of mutable fields such as content, timestamp, and labels.

Path parameter

Sample request

curl -X PATCH \
  'https://api.doit.com/analytics/v1/annotations/Cveqe4ByUxfi3spIueGY' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "labels": [
    "D8Ko0n1ze0Z185HlRfOQ"
     ],
    "content": "Updated annotation"
    }'

Sample response body

{
  "id": "Cveqe4ByUxfi3spIueGY",
  "content": "Updated annotation",
  "timestamp": "2026-01-07T12:04:54.076Z",
  "reports": [
    "HmqMNr1uIMQQySpiBWyt"
  ],
  "labels": [
    {
      "id": "D8Ko0n1ze0Z185HlRfOQ",
      "name": "Platform"
    }
  ],
  "createTime": "2026-01-07T12:36:30.58333Z",
  "updateTime": "2026-01-07T12:41:47.767356Z"
}

Delete an annotation

The deleteAnnotation operation permanently deletes a specific annotation. Once removed, the annotation no longer appears on any reports.

Path parameter

Sample request

curl -X DELETE \
  'https://api.doit.com/analytics/v1/annotations/an_01J9P7C8QBB8RR7E2W8K9J5H3X' \
  -H 'Authorization: Bearer YOUR_API_KEY'

On success, the API returns a 200 response indicating that the annotation has been deleted.

Recommended usage patterns

Some common ways to use the Annotations API in FinOps and CloudOps workflows:

• Automated change markers Integrate with CI or deployment pipelines and create annotations whenever a production change is rolled out. This makes it easy to correlate cost and utilization shifts with specific releases.

• Business event tracking Create annotations when marketing campaigns, pricing changes, or major customer onboarding go live. This helps finance and product teams interpret spend patterns against the business context.

• Anomaly investigation trail When an anomaly is detected and investigated, create an annotation that records the root cause and remediation. This builds a historical trail of learning directly on analytics views.

• Shared “run log” across teams Use labels to categorize annotations by team or domain (for example, ["sre","incident"], ["data-platform","migration"]) and expose them across multiple reports, so different stakeholders can consume the same context without duplicating effort.