Annotations

An annotation records a deploy, a change or a comment next to your telemetry. To mark deploys from CI, start from the Annotations guide.

Anyone in the organization may read annotations. Those on a restricted dataset are visible only to people who can read that dataset. Each endpoint says who may write.

The Annotation object

Badges say what a create request needs: required, optional, or server when Telemetry Machine sets it.

{
  "public_id": "ann_01m5x9q2r7t4k8w3e6y1p0z5ab",
  "type": "deploy",
  "message": "checkout 1.42.0",
  "started_at": "2026-10-26T13:50:04.000Z",
  "ended_at": null,
  "key": "[email protected]@production",
  "dataset": null,
  "attributes": {
    "service.name": "checkout",
    "service.version": "1.42.0",
    "deployment.environment.name": "production",
    "vcs.ref.head.revision": "0b7c0a8e5d1f4c2b9a6e3d7f1c8b4a2e9d5f6c31",
    "url.full": "https://github.com/acme/checkout/actions/runs/123"
  },
  "created_by": null,
  "created_by_api_key": { "public_id": "apk_01m5…", "name": "github actions" },
  "created_by_ci": null,
  "created_at": "2026-10-26T13:50:05.000Z",
  "updated_at": "2026-10-26T13:50:05.000Z"
}

Responses carry it in the API's envelope, as data (refer to Responses).

Create an annotation

Takes the fields of the Annotation object that are marked required or optional. With a key that an annotation already has, it returns that annotation instead of adding one (refer to Keys).

curl -X POST https://telemetrymachine.com/api/organizations/<your-org>/annotations \
  -H "X-API-Key: $TM_INGEST_KEY" -H 'Content-Type: application/json' \
  -d '{
    "type": "deploy",
    "message": "checkout 1.42.0",
    "key": "[email protected]@production",
    "attributes": {
      "service.name": "checkout",
      "service.version": "1.42.0",
      "deployment.environment.name": "production",
      "vcs.ref.head.revision": "0b7c0a8e5d1f4c2b9a6e3d7f1c8b4a2e9d5f6c31"
    }
  }'

POST /api/organizations/<your-org>/annotations
X-API-Key: KEY
Content-Type: application/json

{
  "type": "deploy",
  "message": "checkout 1.42.0",
  "key": "[email protected]@production",
  "attributes": {
    "service.name": "checkout",
    "service.version": "1.42.0",
    "deployment.environment.name": "production",
    "vcs.ref.head.revision": "0b7c0a8e5d1f4c2b9a6e3d7f1c8b4a2e9d5f6c31"
  }
}

{
  "status": 200,
  "data": {
    "public_id": "ann_01m5x9q2r7t4k8w3e6y1p0z5ab",
    "type": "deploy",
    "message": "checkout 1.42.0",
    "started_at": "2026-10-26T13:50:04.000Z",
    "ended_at": null,
    "key": "[email protected]@production"
  }
}

The response is the whole annotation; this one is cut short.

List annotations

Retrieve an annotation

Update an annotation

Updates the fields that you send, and leaves the rest. Setting ended_at turns a moment into a window, such as a load test that you mark when it finishes.

curl -X PATCH https://telemetrymachine.com/api/organizations/<your-org>/annotations/ann_01m5y2k8r4t6w9e3q7p1z0x5cd \
  -H "Authorization: Bearer $TM_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "ended_at": "2026-10-26T15:00:00Z" }'

PATCH /api/organizations/<your-org>/annotations/ann_01m5y2k8r4t6w9e3q7p1z0x5cd
Authorization: Bearer TOKEN
Content-Type: application/json

{ "ended_at": "2026-10-26T15:00:00Z" }

{
  "status": 200,
  "data": {
    "public_id": "ann_01m5y2k8r4t6w9e3q7p1z0x5cd",
    "type": "change",
    "message": "load test of checkout",
    "started_at": "2026-10-26T14:00:00.000Z",
    "ended_at": "2026-10-26T15:00:00.000Z"
  }
}

Delete an annotation

Moments and windows

An annotation is a moment at started_at. With ended_at, it covers a window, such as a load test or a comment on a stretch of a chart. Send ended_at with the annotation, or set it later with Update. Nothing ends an annotation by itself.

Keys

A key is your own id for an annotation, unique in the organization. It makes a create safe to retry, so CI can send the same call again after a timeout.

• Posting a key again returns the existing annotation when every field that you send matches it: a retry. Fields that you leave out aren't compared, so a retry needn't send its time again.
• Posting a key again with a field that differs is refused with 409 Conflict, so two different things never share a key silently.
• A retry is answered even when the organization is at its daily limit.
• A key that another poster holds is a conflict for a CI job: a job retries only the keys that its own repository posted.

A key names everything that makes it unique. Something from another system is <source>:<id>, such as launchdarkly:new-checkout:42 for a flag's 42nd version. A deploy is its service, version and environment, such as [email protected]@production, because the same version often goes to staging and then to production.

Deploy attributes

A deploy must name a commit or a service. These checks run when it is created, and when an update changes its type or attributes. Other names aren't checked, so you can send your own.

Limits

An organization can post 1,000 annotations in 24 hours. More get 429: send events at that volume to an events dataset instead. A retry of a key is still answered.

Errors