Annotations API

Annotations let you 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. (DoiT Help Center)

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. (DoiT Help Center)
• For details, see Roles and permissions in the DoiT Help Center.

Operations

• GET /analytics/v1/annotations Lists annotations.
• GET /analytics/v1/annotations/{id} Retrieves a single annotation.
• POST /analytics/v1/annotations Creates an annotation.
• PATCH /analytics/v1/annotations/{id} Updates an annotation.
• DELETE /analytics/v1/annotations/{id} Deletes an annotation. (DoiT Cloud Intelligence)

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. (DoiT Help Center)

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)

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. (DoiT Cloud Intelligence)

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. (DoiT Cloud Intelligence)

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": "YW5ub3RhdGlvbnNfcGFnZV8y",
  "rowCount": 5,
  "annotations": [
    {
      "id": "an_01J9P6RVQZQH9M8CP3RCWS1F2A",
      "content": "Production EKS cluster resize completed",
      "timestamp": 1730131200000,
      "labels": ["prod-deploy", "kubernetes"],
      "timeCreated": 1730134801234,
      "timeModified": 1730134801234
    },
    {
      "id": "an_01J9P6R1R5MHD3VCSB5F2ZNKXQ",
      "content": "Marketing promotion Black Friday started",
      "timestamp": 1732320000000,
      "labels": ["promo", "business-event"],
      "timeCreated": 1732323604567,
      "timeModified": 1732323604567
    }
  ]
}

Create an annotation

The createAnnotation operation creates a new annotation that can appear on eligible reports for the specified date. (DoiT Cloud Intelligence)

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. (DoiT Help Center)

Sample request

curl -X POST \
  'https://api.doit.com/analytics/v1/annotations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Scaled up GKE nodes in europe-west1",
    "timestamp": 1730419200000,
    "labels": ["capacity-change", "gcp"],
    "visibility": {
      "scope": "all_reports"
    }
  }'

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. (DoiT Cloud Intelligence)

{
  "id": "an_01J9P7C8QBB8RR7E2W8K9J5H3X",
  "content": "Scaled up GKE nodes in europe-west1",
  "timestamp": 1730419200000,
  "labels": ["capacity-change", "gcp"],
  "timeCreated": 1730420100000,
  "timeModified": 1730420100000
}

Retrieve an annotation

The getAnnotation operation returns a single annotation by ID. (DoiT Cloud Intelligence)

Path parameter

Sample request

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

Sample response body

{
  "id": "an_01J9P7C8QBB8RR7E2W8K9J5H3X",
  "content": "Scaled up GKE nodes in europe-west1",
  "timestamp": 1730419200000,
  "labels": ["capacity-change", "gcp"],
  "timeCreated": 1730420100000,
  "timeModified": 1730420100000
}

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. (DoiT Cloud Intelligence)

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/an_01J9P7C8QBB8RR7E2W8K9J5H3X' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Scaled up GKE nodes in europe-west1 for Q4 peak",
    "labels": ["capacity-change", "gcp", "q4-peak"]
  }'

Sample response body

{
  "id": "an_01J9P7C8QBB8RR7E2W8K9J5H3X",
  "content": "Scaled up GKE nodes in europe-west1 for Q4 peak",
  "timestamp": 1730419200000,
  "labels": ["capacity-change", "gcp", "q4-peak"],
  "timeCreated": 1730420100000,
  "timeModified": 1730423705123
}

Delete an annotation

The deleteAnnotation operation permanently deletes a specific annotation. Once removed, the annotation no longer appears on any reports. (DoiT Cloud Intelligence)

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. (DoiT Cloud Intelligence)

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 onboardings go live. This helps finance and product teams interpret spend patterns against 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 learnings 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. (DoiT Help Center)

For filter syntax, pagination behavior, authentication, rate limits, and resource ID semantics, reuse the same concepts described in the generic DoiT API documentation (Get Started, Filters, Resource IDs, and MaxResults and Pagination). (DoiT Cloud Intelligence)