Skip to main content
Metabase shows you that a number moved: a funnel dropped, an error-rate tile climbed, a cohort in a table looks wrong. It reads your warehouse and charts the shape of the problem, but it can’t show you the moment one specific person hit it. Subtext can. Point Metabase at a subtext_url column your collector already landed and every dashboard row becomes a jumping-off point — your agent reads the subtext_url, opens that person’s real session, and walks the decisive moments with screenshots, the component tree, network, and console. Metabase detects; Subtext diagnoses.
This guide assumes the Subtext capture snippet is installed and capturing sessions, and that Metabase is connected to a warehouse table with a subtext_url column that a collector (Snowplow, Hightouch, Segment, or direct inserts) already landed.

​
Attach the session URL

Metabase doesn’t capture anything — it reads a subtext_url column your collector already landed in the warehouse. Attaching the link is configuration, not code: return the column in a question, then format it as a link so every row opens the session. The examples assume ClickHouse, but the steps are identical on any warehouse Metabase connects to.

​
Return the column in a question

Write a question that selects subtext_url alongside whatever you are analyzing:
In the question’s visualization settings, open the subtext_url column and set Display As → Link. The column already holds a full URL, so the link template is just the value itself. Store the full subtext_url as captured — the signed URL originates in the browser via FS('getSession') and can’t be reconstructed from a bare session id, so a link template can’t rebuild it:
Set Link text to Open session (or leave it blank to show the URL). Now every row renders an Open session link that opens the replay in a new tab.

​
Make it stick with a model

Set the formatting once on a Metabase model and every question and dashboard built on that model inherits the clickable link automatically. Add the subtext_url column to the model, set its display to Link in the model’s metadata, and downstream questions render it without re-configuring.
Don’t put a question that exposes subtext_url into a public link or static embed — the signed URL grants replay access, so keep these questions and dashboards to authenticated, internal users. Don’t wrap the raw URL in LowCardinality upstream or truncate it in the query; the full signed string is required for the link to resolve. And don’t rely on the link for rows written before the collector attached subtext_url — filter subtext_url != '' so empty rows don’t render dead links.

​
From signal to session

However you first hear about a problem in Metabase, the path is the same: click the Open session link, grab the subtext_url, and hand it to your agent for a Detect-vs-Diagnose read — the dashboard says these users errored or dropped; the session shows what they actually experienced.
The analyst or growth PM reviewing the weekly funnel dashboard sees a funnel or error-rate tile below trend. The linked question lists the affected users, each row with an Open session link.Click into the question behind the tile and copy a few Open session links (or right-click → copy link). Then hand them to your agent:
The data analyst exploring ad-hoc slices a question and one segment looks wrong — high error rate, low completion. Each row already carries an Open session link.
A Metabase alert on a question crosses its threshold (error count spikes, conversion drops) and emails anyone subscribed to it. Open the question from the alert email; the offending rows carry Open session links.
For a funnel investigation across several users, ask your agent to consolidate its findings into one proof document (doc-create) with a screenshot per dropped user and a single shareable link — then drop that back into the dashboard’s description so the tile carries the human story behind it.

​
For agents

An autonomous agent can run the whole loop against Metabase: run the analysis your team already trusts, extract the subtext_url, and hand each session to the Subtext MCP. Metabase ships an official first-party MCP server (Metabase 60+, available on all plans), built into your instance and served from the /api/metabase-mcp endpoint. Clients authenticate via OAuth 2.0 against Metabase’s embedded OAuth server, with tokens scoped to the connecting user’s Metabase permissions, and it requires AI features to be enabled — if AI features are off in Admin > AI, the MCP server stays off. Its read-only tools — search, read_resource, construct_query, execute_query, query — run queries and return rows with column metadata. The Metabase REST API remains an alternative path, and POST /api/card/<card_id>/query/json is still the single-call way to run a saved question: the MCP server has no run-card-by-id tool, so an agent reads the question via read_resource (metabase://question/<id>) and then constructs and executes its query. Metabase is a convenience layer over your warehouse, so you can also skip it entirely and query the underlying warehouse through its own MCP (for ClickHouse, the official mcp-clickhouse server). The official server also exposes write tools (create_question, execute_sql, and more), so connect as a Metabase user with read-only permissions — the OAuth token inherits that user’s permissions — and note that an admin can disable execute_sql instance-wide via the mcp-execute-sql-enabled setting.
1

Discover who is affected

Run the saved question (card) that already encodes the funnel, error, or cohort analysis — a card contains the exact analysis your team trusts. Via the official Metabase MCP server or the REST API directly:
2

Extract the session URL

Read subtext_url off the returned rows:
To build the query fresh instead, run SQL against the warehouse MCP directly for the same rows.
3

Hand off to Subtext

For each URL, call review-open(session_url=<subtext_url>) on the Subtext MCP and step through the drop or error moment for a Detect-vs-Diagnose read.
The card must actually select subtext_url and filter out empty values, or the field won’t be in the result — check the question’s columns first. A card returns whatever row limit the question sets, so raise it or paginate for a full cohort. Use read-only credentials on whichever surface you pick: a review agent only reads. And subtext_url only round-trips if a collector attached it (see Attach the session URL).