Annotations
Mark releases, live events, incidents and experiment changes on every time chart in your project, so you can see what changed when a metric moves.
Annotations mark moments and periods on every time chart in your project. Use them for a release, a live event, a sale, an outage, or anything else that might explain why a metric moved. Each annotation is either a point (a single moment) or a range (a start and an end).
Annotations belong to the project, not to one chart: add one and it shows on every time chart, dashboard and query in that project. They follow the environment switcher, so production and development annotations stay separate.
Experiments are annotated for you. When an experiment starts, Gamebeast adds a range for it, and each rollout change (paused, resumed, percentage changed) adds a point.
Types
Every annotation has a type, such as Releases, Live events or Incidents. A type sets the icon and color the annotation is drawn with, and lets charts show or hide a whole group at once.
- Types are defined per project. Create them from the Annotations tab or straight from a chart while adding an annotation.
- Each type has a name, an optional description, an icon, a color, and whether charts show it by default.
- Archive a type to hide it from charts and pickers without losing its annotations. Restore it any time. A type with no annotations can be deleted.
- Gamebeast's own types, Experiments and Experiment rollouts, are marked with a lock. You can change their color and whether they show by default, but not rename them, archive them or add annotations to them by hand. Experiment rollouts are hidden by default.
Adding an annotation
From a chart. Under every time chart is a thin strip where annotations sit.
- Click the strip to add a point at that time.
- Drag along the strip to add a range.
- Or select + beside the filter button at the left of the strip.
A small form opens with the type, name and time filled in. Add a description or link if you like, then save.
From the Annotations tab. Open Data > Annotations and choose New annotation. This is also where you see every annotation in a searchable table, filter by type or by who added it, and edit or delete any of them.
Anyone who can edit annotations can change or delete any custom annotation, not only their own. Annotations Gamebeast wrote for experiments are read-only: change the experiment instead.
Reading annotations on a chart
- Points show as chips on the strip. Hover one to see its name, time, description, who added it and its link. Nearby points are grouped so they stay readable.
- Ranges show as labelled bars. When several ranges overlap, they fold into a compact track; hover it to see every range at that moment.
- A range that is still running (an experiment with no end date, for example) extends to now.
- Use the filter button at the left of the strip to choose which types a board shows. The choice is saved per board in your browser.
Share links
Annotations are off on share links until you turn them on. When creating or editing a share link, select Show annotations and pick which types the link includes. Viewers see those annotations on the shared charts, without the names of the people who added them.
Sources: annotations from GitHub and CI
A source is a webhook URL that turns events from another tool into annotations, so releases and deploys appear on your charts without anyone adding them by hand. Each source writes one annotation type, in the environment it was created in.
Open Data > Annotations, then choose New source under Sources. Pick GitHub or Generic JSON, pick the type to write, and choose Get the webhook URL.
The URL is the credential: anyone with it can add annotations. Keep it in your CI's secret store, not in a public repository. If it leaks, delete the source and create a new one.
GitHub
In your repository, open Settings > Webhooks > Add webhook and fill in:
| GitHub field | Value |
|---|---|
| Payload URL | The source's URL |
| Content type | application/json |
| Secret | The secret Gamebeast shows when you create the source (shown once) |
| Events | Let me select individual events, then Releases and Deployment statuses |
GitHub sends a test ping when you save, and the source shows it arrived. After that:
- A published release becomes a point named Release v1.45.0, linked to the release.
- A successful deployment becomes a point named Deployed main to production, linked to its log.
- Pushes, drafts, failed deployments and other events are received but not annotated.
Every request is checked against the secret. If you lose it, choose Rotate secret on the source; the old secret stops working at once.
Generic JSON
Send a POST with a JSON body to the source's URL. A body that uses these field names works with no setup:
| Field | Meaning |
|---|---|
name | The label on the chart (required) |
description | Optional text |
startsAt | When it happened: ISO 8601, or epoch seconds or milliseconds. Defaults to when it arrived |
endsAt | Makes it a range |
url | An https link |
idempotencyKey | Any string; sending the same key again does not add a second annotation |
curl -X POST "$GAMEBEAST_ANNOTATIONS_URL" \
-H "content-type: application/json" \
-d '{"name":"Winter sale","startsAt":"2026-12-01T00:00:00Z","endsAt":"2026-12-08T00:00:00Z"}'To annotate each deploy from GitHub Actions, store the URL as a repository secret and add a step:
- name: Annotate deploy
run: |
curl -sf -X POST "${{ secrets.GAMEBEAST_ANNOTATIONS_URL }}" \
-H "content-type: application/json" \
-d "{\"name\":\"Deploy ${GITHUB_SHA::7}\",\"idempotencyKey\":\"${{ github.run_id }}\"}"You can also require a secret: turn on Require a secret when creating the source (or choose Add secret later), then send it in the x-gamebeast-secret header.
Mapping other payloads
If your tool sends its own format, map it. Once the first event arrives, the source shows what it becomes. Choose Customize mapping to set each field to a template, such as Deploy {{deploy.version}}, where {{...}} is a path into the payload. The field picker lists every field in the last payload, and the preview updates as you type.
Only when lets one source ignore some events: status == finished annotates only payloads whose status is finished. Use != for the opposite.
Deliveries
Each source keeps its last 20 deliveries, with what happened to each:
| Status | Meaning |
|---|---|
| Created | An annotation was added |
| Already added | The same event arrived again (same idempotency key); nothing new was added |
| Received | The payload was stored but not annotated: GitHub's test ping, or no mapping yet |
| Skipped | Not annotated: an event this source ignores, a failed Only when test, or no name |
| Rejected | The signature or secret didn't match, or the body wasn't JSON |
| Failed | The source's settings are wrong, for example its type was archived |
Gamebeast answers every accepted request with 200, including skipped ones, so tools don't retry forever. A bad signature or secret gets 401. Turning a source off keeps its URL but stops it adding annotations. Deleting a source keeps the annotations it already added.
From the assistant and MCP
The assistant and MCP clients can read and write annotations:
| Tool | Use it for |
|---|---|
list_annotations | Find what happened around a date: releases, events, incidents |
list_annotation_types | See the project's types |
create_annotation | Add a point or range |
update_annotation | Change one |
delete_annotation | Remove one |
create_annotation_type | Add a type |
When the assistant explains a change in a metric, it looks at the annotations in that window, so "why did retention drop last week?" can point at the release that shipped that day. In the assistant, every write asks for your approval first. Annotations it adds show Assistant or MCP as their source.
API
Annotations are available from the API with a personal access token:
GET /application/{applicationId}/analytics/v1/annotationslists annotations, newest first. Passfromandtofor the ones overlapping a window, and filter by type, source or text.POST,PATCHandDELETEon the same path add, change and remove them. Send anidempotencyKeywhen creating from a script so a retry doesn't add a duplicate./annotations/typeslists and manages types.
Every request takes an environment-id header. See the API reference for every parameter. Sources can only be managed from the dashboard.
Who can do what
| Permission | Allows | Built-in roles |
|---|---|---|
annotations:read | Seeing annotations on charts, the Annotations tab | Viewer and above |
annotations:write | Adding, editing and deleting annotations, types and sources | Editor and above |
Grant either to custom roles in Settings > Roles. Every change to an annotation, type or source is recorded in the audit log.
Dashboards
Dashboards put your saved charts, section headings, notes and images on a grid you arrange yourself, with one set of controls for every chart, folders in the sidebar, and public links for people outside your team.
Query Builder
Turn the markers your experience sends into charts: pick a query type, choose what to measure, filter and break it down, set the time range and chart, then save it to a dashboard or share it.