> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# List annotations

> Lists annotations, optionally filtered by datasets and time.

`axiom.listAnnotations` lists annotations. You can limit results to selected datasets or a time range. Results include IDs, type, timestamps, and optional title, description, URL, and end time.

```ts automations/axiom-list-annotations.automation.ts theme={null}
import { automation, onHttpRequest } from "automate.ax"
import { axiom } from "automate.ax/axiom"

export default automation("List annotations", () => {
  onHttpRequest({ scope: "automation" })
  axiom.listAnnotations({
    datasets: ["production"],
    startTime: "2026-08-01T00:00:00Z",
    endTime: "2026-09-01T00:00:00Z",
  })
})
```

## Inputs

All inputs are optional. `datasets` filters by dataset names or IDs. `startTime` and `endTime` bound the annotation window using Axiom time expressions or timestamps. Omitting all three returns every annotation visible to the token.

## Output

Returns an array of annotations. Each item includes `id`, `datasets`, `type`, and `time`, plus `endTime`, `title`, `description`, and `url` when present. An empty match returns `[]`.

## Permission and failures

The API token needs the organization-level `annotations|read` capability. Axiom rejects invalid time expressions; authentication and permission failures are returned as action errors.