# Annotations





Annotations show when deployments, outages, or other configured events happened alongside your data. Mark a point or interval in time across Query, dashboards, and monitors to put changes in context.

## Prerequisites [#prerequisites]

* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets#create-dataset) where you send your data.
* [Send data](/send-data/methods) to your Axiom dataset.
* To view annotations in Console, use an account with permission to read annotations.
* For API requests and GitHub Actions, [create an API token](/reference/tokens) with the annotation permissions for the operations you use: create, read, update, or delete.

## Show and hide annotations in Console [#show-and-hide-annotations-in-console]

### Query [#show-and-hide-annotations-in-query]

Annotations appear on time series and percentile charts, and on heatmaps when the query returns a single chart. Use **Chart options** to show or hide annotations for the queried dataset and selected time range.

### Dashboards [#show-and-hide-annotations-on-dashboards]

To choose the annotation types to display, click **Annotations** in the dashboard toolbar.

In the chart editor, expand **Chart** and click **Manage** in **Annotations**.

Each chart shows annotations for the datasets it queries. Your selections apply across the dashboard and aren't saved with it.

### Monitors [#show-and-hide-annotations-in-monitors]

Threshold and anomaly monitor charts show annotations for the monitor’s dataset and the chart’s time range.

<p id="monitor-detail-pages" className="scroll-mt-[32px]">
  In <strong>Recent activity</strong>, click <strong>Annotations</strong> beside the time range and select the types to display. On phones, open <strong>Recent activity options</strong> (<code>⋯</code>) and select <strong>Annotations</strong>.
</p>

<p id="show-and-hide-annotations-in-monitor-previews" className="scroll-mt-[32px]">
  In the monitor editor, run the preview query. Expand <strong>Chart</strong> in the settings panel and click <strong>Manage</strong> in <strong>Annotations</strong>.
</p>

Your selections aren't saved with the monitor.

## Display limits [#display-limits]

For time ranges longer than 100 days, charts show annotations only for the latest 100 days of that range. To view older annotations, select a shorter range around the event.

## Create annotations [#create-annotations]

Create annotations with a [GitHub Action](#create-annotations-with-github-actions) or the [Axiom API](#create-annotations-using-axiom-api). The [Axiom Vercel integration](/apps/vercel) also creates annotations when deployments complete.

### Create annotations with GitHub Actions [#create-annotations-with-github-actions]

Add the [Axiom annotation action](https://github.com/axiomhq/annotation-action) after the deployment step in your workflow:

```yml
- name: Add deployment annotation
  uses: axiomhq/annotation-action@v0.2.0
  with:
    axiomToken: ${{ secrets.API_TOKEN }}
    datasets: DATASET_NAME
    type: "production-release"
    title: "Production deployment"
    description: "Commit ${{ github.event.head_commit.message }}"
```

<Info>
  <ReplaceDatasetToken />
</Info>

By default, the action uses the current time and links to the workflow run.

### Create annotations using Axiom API [#create-annotations-using-axiom-api]

To create an annotation using the Axiom API, use the following API request:

```bash
curl -X 'POST' 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": "2024-03-18T08:39:28.382Z",
    "type": "deploy",
    "datasets": ["DATASET_NAME"],
    "title": "Production deployment",
    "description": "Deploy new feature to the sales form",
    "url": "https://example.com"
  }'
```

<Info>
  <ReplaceDatasetToken />
</Info>

Customize the other fields of the code above such as the title, the description, and the URL. For more information on the allowed fields, see [Annotation object](#annotation-object).

**Example response**

```json
{
  "datasets": ["my-dataset"],
  "description": "Deploy new feature to the sales form",
  "id": "ann_123",
  "time": "2024-03-18T08:39:28.382Z",
  "title": "Production deployment",
  "type": "deploy",
  "url": "https://example.com"
}
```

The API response from Axiom contains an `id` field. This is the annotation ID that you can later use to change or delete the annotation.

## Get information about annotations [#get-information-about-annotations]

To list annotations in your organization, use the following API request:

```bash
curl -X 'GET' 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN'
```

<Info>
  <ReplaceToken />
</Info>

Without filters, this endpoint returns all annotations in your organization. Use the following parameters to filter by time range or dataset:

* `start` is an RFC 3339 timestamp that specifies the beginning of the time interval.
* `end` is an RFC 3339 timestamp that specifies the end of the time interval.
* `datasets` is the list of datasets whose annotations you want to get information about. Separate datasets by commas, for example `datasets=my-dataset1,my-dataset2`.

Set both `start` and `end`, or omit both. Use a range of 100 days or less, with `end` at or after `start`. Results include annotations that overlap the range.

The following example lists annotations for `my-dataset` between March 16 and 19, 2024:

```bash
curl -X 'GET' 'https://api.axiom.co/v2/annotations?start=2024-03-16T00:00:00.000Z&end=2024-03-19T23:59:59.999Z&datasets=my-dataset' \
  -H 'Authorization: Bearer API_TOKEN'
```

**Example response**

```json
[
  {
    "datasets": ["my-dataset"],
    "description": "Deploy new feature to the navigation component",
    "id": "ann_234",
    "time": "2024-03-17T01:15:45.232Z",
    "title": "Production deployment",
    "type": "deploy",
    "url": "https://example.com"
  },
  {
    "datasets": ["my-dataset"],
    "description": "Deploy new feature to the sales form",
    "id": "ann_123",
    "time": "2024-03-18T08:39:28.382Z",
    "title": "Production deployment",
    "type": "deploy",
    "url": "https://example.com"
  }
]
```

The API response from Axiom contains an `id` field. This is the annotation ID that you can later use to change or delete the annotation. For more information on the other fields, see [Annotation object](#annotation-object).

To get information about a specific annotation, use the following API request:

```bash
curl -X 'GET' 'https://api.axiom.co/v2/annotations/ANNOTATION_ID' \
  -H 'Authorization: Bearer API_TOKEN'
```

<Info>
  Replace `ANNOTATION_ID` with the ID of the annotation.

  <ReplaceToken />
</Info>

**Example response**

```json
{
  "datasets": ["my-dataset"],
  "description": "Deploy new feature to the sales form",
  "id": "ann_123",
  "time": "2024-03-18T08:39:28.382Z",
  "title": "Production deployment",
  "type": "deploy",
  "url": "https://example.com"
}
```

For more information on these fields, see [Annotation object](#annotation-object).

## Change annotations [#change-annotations]

To change an existing annotation, use the following API request:

```bash
curl -X 'PUT' 'https://api.axiom.co/v2/annotations/ANNOTATION_ID' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "endTime": "2024-03-18T08:49:28.382Z"
  }'
```

<Info>
  Replace `ANNOTATION_ID` with the ID of the annotation. For more information about how to determine the annotation ID, see [Get information about annotations](#get-information-about-annotations).

  <ReplaceToken />

  In the payload, specify the fields to change. Omitted fields keep their current values. Empty text values and an empty `datasets` list leave existing values unchanged. The example adds `endTime` to the annotation created above. For more information, see [Annotation object](#annotation-object).
</Info>

**Example response**

```json
{
  "datasets": ["my-dataset"],
  "description": "Deploy new feature to the sales form",
  "id": "ann_123",
  "time": "2024-03-18T08:39:28.382Z",
  "title": "Production deployment",
  "type": "deploy",
  "url": "https://example.com",
  "endTime": "2024-03-18T08:49:28.382Z"
}
```

## Delete annotations [#delete-annotations]

To delete an existing annotation, use the following API request:

```bash
curl -X 'DELETE' 'https://api.axiom.co/v2/annotations/ANNOTATION_ID' \
  -H 'Authorization: Bearer API_TOKEN'
```

<Info>
  Replace `ANNOTATION_ID` with the ID of the annotation. For more information about how to determine the annotation ID, see [Get information about annotations](#get-information-about-annotations).

  <ReplaceToken />
</Info>

## Annotation object [#annotation-object]

Annotations are represented as objects with the following fields:

* `datasets` is the list of dataset names for which the annotation appears on charts. Specify at least one existing dataset when creating an annotation.
* `id` is the unique ID of the annotation.
* `time` is the start time of the annotation, in RFC 3339 format. If you omit this field when creating an annotation, Axiom uses the time of the API request. Axiom rejects future start times.
* Optional: `endTime` is the end time of the annotation, in RFC 3339 format. Specify an end time at or after `time`. Omit this field when creating an annotation to mark a point in time.
* `type` is the type of event marked by the annotation. For example, `production-deployment`. Specify this field when creating an annotation. Use lowercase letters, numbers, and hyphens.
* Optional: `title` is a summary of the annotation that appears on the charts.
* Optional: `description` is an explanation of the event the annotation marks on the charts.
* Optional: `url` is the URL relevant for the event marked by the annotation. For example, a link to a GitHub pull request.

For more information, see [Create annotation](/restapi/endpoints/createAnnotation), [List all annotations](/restapi/endpoints/getAnnotations), and [Update annotation](/restapi/endpoints/updateAnnotation).

## Example use case [#example-use-case]

The example below demonstrates how annotations help you troubleshoot issues in your app or system. Your monitor alerts you about rising form submission errors. You explore this trend and when it started. Right before form submission errors started rising, you see an annotation about a deployment of a new feature to the form. You make the hypothesis that the deployment is the reason for the error and decide to investigate the code changes it introduced.

### Create annotation [#create-annotation]

Use the following API request to create an annotation:

```bash
curl -X 'POST' 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": "2024-03-18T08:39:28.382Z",
    "type": "deploy",
    "datasets": ["my-dataset"],
    "title": "Production deployment",
    "description": "Deploy new feature to the sales form",
    "url": "https://example.com"
  }'
```

<Info>
  <ReplaceToken />
</Info>

### Create a monitor [#create-a-monitor]

In this example, you set up a monitor that alerts you when the number of form submission errors rises. For more information on creating a monitor, see [Monitoring and Notifiers](/monitor-data/monitors).

### Explore trends [#explore-trends]

Suppose your monitor sends you a notification about rising form submission errors.

You decide to investigate and run a query to display the number of form submission errors over time. Ensure you select a time range that includes the annotation.

You get a chart similar to the example below displaying form submission errors and annotations about the time of important events such as deployments.

<Frame caption="Form submission errors with a deployment annotation">
  <img src="/docs/doc-assets/shots/annotation-chart-example.png" alt="Form submission errors with a deployment annotation" />
</Frame>

### Inspect issue [#inspect-issue]

1. From the chart, you see that the number of errors started to rise after the deployment of a new feature to the sales form. This correlation allows you to form the hypothesis that the errors might be caused by the deployment.
2. You click the annotation’s link to investigate the deployment.
3. You inspect the code changes in depth and discover the cause of the errors.
4. You quickly fix the issue in another deployment.
