How do I share an Altair chart as a link?

`chart.save('chart.html')` writes a standalone page, then publish that file — one curl, or drag it into the app. You get a URL where the tooltips, panning and linked selections still work, because the chart's JavaScript runs at the link.

Does Altair's HTML need the internet?

By default yes — the saved page loads Vega, Vega-Lite and vega-embed from jsDelivr. That CDN is allow-listed, so the chart renders at the link. If your audience may be offline, `chart.save('chart.html', inline=True)` bundles the libraries into the file instead (it needs vl-convert installed).

Can I publish several charts as one report?

Yes. Compose them in Altair first — `chart1 | chart2`, `chart1 & chart2`, or a `concat` — and save the composed chart, so the interactions stay linked. Or write your own HTML around several saved charts and publish that.

How do I refresh it when the data changes?

PATCH the same report id with the newly saved HTML, or put the script on a routine. The URL is stable and each refresh appends a revision, so a chart in a wiki page or an email signature never goes stale.

Can someone comment on a specific point?

Yes. Threads anchor to the rendered content, so 'what happened in week 32?' sits on the chart rather than arriving as a cropped screenshot with an arrow on it.

Share an Altair chart

The reason to use Altair rather than matplotlib is the interaction — the tooltip, the brush selection, the linked view that filters the other panel. Every one of those is destroyed by the way charts usually get shared, which is a PNG pasted into a channel.

import altair as alt

chart = alt.Chart(df).mark_circle().encode(
    x="week:O", y="latency_p95:Q", color="service:N",
    tooltip=["service", "week", "latency_p95"],
).interactive()

chart.save("chart.html")

Publish the file

curl -X POST https://commareports.com/api/v1/reports \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html chart.html \
        '{title: "p95 latency by service", html: $html}')"

Or drag chart.html into the app.

The chart keeps working at the link. Report HTML renders with scripts enabled inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the Vega runtime initialises and the zoom, tooltips and selections behave exactly as they do in your notebook — see interactive HTML reports.

Online vs. self-contained

chart.save() writes a page that loads Vega, Vega-Lite and vega-embed from jsDelivr, which is allow-listed — the chart renders at the link without further work.

Use chart.save("chart.html", inline=True) (with vl-convert-python installed) when the audience might be offline or on a locked-down network. The file gets larger; it stops depending on anything.

Chart plus narrative

A chart on its own answers a question nobody asked. Build the page in Python and publish that instead:

html = f"""
<h1>p95 latency, weeks 20–40</h1>
<p>Two services regressed after the connection-pool change in week 32.</p>
{chart.to_html()}
"""

Then POST html. The same trick works for a composed view — (chart1 | chart2) keeps the selections linked across both panels.

Keeping it current

PATCH the same report id when the data refreshes, or run the script on a routine so the URL you pasted into the wiki three months ago still shows this week's numbers. Each refresh appends a revision, so the change is inspectable rather than silent.

Limits

Entry HTML: 5 MB. Altair inlines the data by default, so a chart over a large frame can pass that — aggregate before plotting, or reference the data as an asset URL.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish an interactive chart →