formatting-insight-axes

PostHog renders insights with a built-in axis formatter. Use it instead of contorting the query or a literal prefix/postfix to fake units.

The two insight kinds configure it in different places:

• TrendsQuery — trendsFilter.aggregationAxisFormat (this page, below)
• SQL insights (DataVisualizationNode) — per-column settings.formatting (see SQL insights)

If you are reaching for any of these, stop and pick a format below first:

• formula: "A / 60" with aggregationAxisPostfix: " mins" — manual seconds -> minutes
• formula: "A / 1000" with aggregationAxisPostfix: " s" — manual ms -> seconds
• formula: "A * 100" with aggregationAxisPostfix: "%" — manual ratio -> percent
• aggregationAxisPostfix: "ms" / "s" / "min" / "hr" on raw values

These freeze the unit at one scale. The built-in formatter picks a friendly unit per value (1.5s, 2m 12s, 1h 4m) and keeps the underlying series numerically correct for further math, breakdowns, and alerts.

Set trendsFilter.aggregationAxisFormat on the TrendsQuery:

Companion fields on trendsFilter:

• aggregationAxisPrefix — literal prefix (e.g. "$") when you need a symbol pinned to a specific currency or unit, regardless of project settings
• aggregationAxisPostfix — literal suffix; reserve for genuine units the format can't express (e.g. " req", " events"), never for "mins" / "s" / "%" — the percentage formats already append the % sign, so a "%" postfix renders 50%%
• decimalPlaces — cap decimals (1 or 2 is usually right for currency / ratios)

If the series is in seconds (latency, session length, time-to-first-event, processing time, page load, etc.), silently default to aggregationAxisFormat: "duration". Do not stop to ask — the formatter is non-destructive (the underlying values stay in seconds either way, only the labels change), so picking it is always at least as good as raw seconds.

Only confirm with the user when they have explicitly named a fixed unit they want pinned ("show this in minutes", "graph the average in hours"):

"I can pin the y-axis to minutes by dividing the series by 60, or use PostHog's duration formatter which auto-picks seconds / minutes / hours per value — 90s renders as 1m 30s and 5400s as 1h 30m. Which would you prefer?"

In one-shot MCP contexts where no user is in the loop, just pick duration and move on.

SQL insights have no trendsFilter. Formatting is per column, on chartSettings.yAxis[].settings.formatting for a chart and top-level tableSettings.columns[].settings.formatting for a table.

{
  "kind": "DataVisualizationNode",
  "source": { "kind": "HogQLQuery", "query": "SELECT week, conversion_rate FROM ..." },
  "display": "ActionsLineGraph",
  "chartSettings": {
    "xAxis": { "column": "week" },
    "yAxis": [
      {
        "column": "conversion_rate",
        "settings": { "formatting": { "style": "percent", "decimalPlaces": 1 } }
      }
    ]
  }
}

style is none, number, short, or percent — no duration or currency. Express those with prefix / suffix, or in the SQL itself.

percent both appends the % sign and multiplies the value by 100 (like the trends percentage_scaled format; there is no unscaled variant). So feed it a 0-1 ratio and leave suffix unset — pick one shape, never a mix:

A mix renders broken: style: "percent" plus a "%" suffix gives 47.3%%, and percent on an already-scaled 0-100 column gives 4730%. Prefer the ratio form — it keeps the 100.0 * out of the query, so the stored column stays a plain ratio for anything else that reads it.

If an insight you are already editing uses one of these anti-patterns — a trends formula/postfix pair, or a SQL column with both style: "percent" and a "%" suffix — fix it in the same posthog:insight-update call: drop the divide-by-N or 100.0 * and the literal %, and let the format own the unit. Values stay the same, only labels change. Do not scan unrelated insights — fix only the ones you are already touching.