Formatting Insight Axes

1---
2name: formatting-insight-axes
3description: >
4  Pick the right y-axis unit when creating or updating a TrendsQuery insight
5  via `posthog:insight-create` or `posthog:insight-update`. Use when the agent
6  is about to add a `formula` purely to convert units (e.g. dividing seconds
7  by 60 to display minutes), when a `math_property` is a duration, currency,
8  ratio, or large count, or whenever the user mentions "format the y-axis",
9  "duration", "seconds", "minutes", "hours", "milliseconds", "ms",
10  "percentage", "currency", "decimals", "axis label", or "axis unit" in the
11  context of a graph insight.
12---
13 
14# Formatting insight axes
15 
16PostHog renders TrendsQuery insights with a built-in axis formatter. Use it
17instead of contorting `formula` or `aggregationAxisPostfix` to fake units.
18 
19## The anti-pattern
20 
21If you are reaching for any of these, stop and pick a format below first:
22 
23- `formula: "A / 60"` with `aggregationAxisPostfix: " mins"` — manual seconds -> minutes
24- `formula: "A / 1000"` with `aggregationAxisPostfix: " s"` — manual ms -> seconds
25- `formula: "A * 100"` with `aggregationAxisPostfix: "%"` — manual ratio -> percent
26- `aggregationAxisPostfix: "ms"` / `"s"` / `"min"` / `"hr"` on raw values
27 
28These freeze the unit at one scale. The built-in formatter picks a friendly
29unit per value (1.5s, 2m 12s, 1h 4m) and keeps the underlying series numerically
30correct for further math, breakdowns, and alerts.
31 
32## Available formats
33 
34Set `trendsFilter.aggregationAxisFormat` on the TrendsQuery:
35 
36| Value               | Use when the series is...                | Renders as                  |
37| ------------------- | ---------------------------------------- | --------------------------- |
38| `numeric` (default) | a plain count                            | `1,234`                     |
39| `duration`          | **seconds** (any scale)                  | `45s`, `2m 12s`, `1h 4m`    |
40| `duration_ms`       | **milliseconds**                         | `850ms`, `1.5s`, `1m 4s`    |
41| `percentage`        | already 0-100                            | `47.3%`                     |
42| `percentage_scaled` | a ratio 0-1                              | `47.3%`                     |
43| `currency`          | money in the **project's base currency** | `$1,234.56` (or local code) |
44| `short`             | large counts you want compacted          | `1.2K`, `3.4M`              |
45 
46Companion fields on `trendsFilter`:
47 
48- `aggregationAxisPrefix` — literal prefix (e.g. `"$"`) when you need a symbol
49  pinned to a specific currency or unit, regardless of project settings
50- `aggregationAxisPostfix` — literal suffix; reserve for genuine units the
51  format can't express (e.g. `" req"`, `" events"`), never for `"mins"` /
52  `"s"` / `"%"` — the percentage formats already append the `%` sign, so a
53  `"%"` postfix renders `50%%`
54- `decimalPlaces` — cap decimals (1 or 2 is usually right for currency / ratios)
55 
56### Currency — pick `format` or `prefix` carefully
57 
58`aggregationAxisFormat: "currency"` renders with the **project's base currency**
59(set in project settings, defaults to USD). Use it when the underlying values
60are in that same currency — e.g. revenue events that PostHog auto-converts to
61the project's base currency.
62 
63If the values are pinned to a specific currency regardless of project (e.g.
64`$ai_total_cost_usd` is always USD, even on a EUR-base project), use
65`aggregationAxisPrefix: "$"` + `decimalPlaces: 2` so the symbol matches the
66data. Using `format: "currency"` here would render USD values with `€` on a
67EUR project.
68 
69## When the series is in seconds
70 
71If the series is in seconds (latency, session length, time-to-first-event,
72processing time, page load, etc.), silently default to
73`aggregationAxisFormat: "duration"`. Do not stop to ask — the formatter is
74non-destructive (the underlying values stay in seconds either way, only the
75labels change), so picking it is always at least as good as raw seconds.
76 
77Only confirm with the user when they have **explicitly** named a fixed unit
78they want pinned ("show this in minutes", "graph the average in hours"):
79 
80> "I can pin the y-axis to minutes by dividing the series by 60, or use
81> PostHog's `duration` formatter which auto-picks seconds / minutes / hours
82> per value — `90s` renders as `1m 30s` and `5400s` as `1h 30m`. Which would
83> you prefer?"
84 
85In one-shot MCP contexts where no user is in the loop, just pick `duration`
86and move on.
87 
88## Examples
89 
90### Latency — duration in milliseconds
91 
92```json
93{
94  "kind": "TrendsQuery",
95  "series": [
96    {
97      "kind": "EventsNode",
98      "event": "$pageview",
99      "math": "p95",
100      "math_property": "$performance_page_loaded"
101    }
102  ],
103  "trendsFilter": {
104    "aggregationAxisFormat": "duration_ms"
105  }
106}
107```
108 
109### Average session length — duration in seconds
110 
111```json
112{
113  "kind": "TrendsQuery",
114  "series": [
115    {
116      "kind": "EventsNode",
117      "event": "$pageleave",
118      "math": "avg",
119      "math_property": "$session_duration"
120    }
121  ],
122  "trendsFilter": {
123    "aggregationAxisFormat": "duration"
124  }
125}
126```
127 
128### Revenue — currency in the project's base currency
129 
130```json
131{
132  "trendsFilter": {
133    "aggregationAxisFormat": "currency",
134    "decimalPlaces": 2
135  }
136}
137```
138 
139### Fixed-currency value (e.g. LLM cost in USD) — pin the symbol
140 
141```json
142{
143  "trendsFilter": {
144    "aggregationAxisPrefix": "$",
145    "decimalPlaces": 2
146  }
147}
148```
149 
150### Conversion rate — percentage from a 0-1 formula
151 
152```json
153{
154  "kind": "TrendsQuery",
155  "series": [
156    {
157      "kind": "EventsNode",
158      "event": "checkout_completed",
159      "math": "dau"
160    },
161    {
162      "kind": "EventsNode",
163      "event": "checkout_started",
164      "math": "dau"
165    }
166  ],
167  "trendsFilter": {
168    "formula": "A / B",
169    "aggregationAxisFormat": "percentage_scaled",
170    "decimalPlaces": 1
171  }
172}
173```
174 
175## Updating an existing insight
176 
177If you are updating an insight and notice it already uses the
178`formula`/`postfix` anti-pattern, fix it in the same `posthog:insight-update`
179call — drop the divide-by-N, drop the `aggregationAxisPostfix`, and set the
180matching `aggregationAxisFormat`. The series values stay the same, only the
181labels change. Do not go scanning unrelated insights for this pattern —
182fix only the ones you are already touching.
183