Appcues and Subtext: From a Flow to the Session

Appcues tells you that an onboarding flow leaked users: a step was skipped, a flow abandoned, a variant underperformed. It can’t show you what the user actually saw when that step appeared. Subtext can. Attach the Subtext session URL to the Appcues user profile and every flow signal 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. Appcues detects; Subtext diagnoses.

This guide assumes the Subtext capture snippet is installed and capturing sessions, and the Appcues Web SDK snippet is loaded (window.Appcues is available).

Attach the session URL

Store the current Subtext session URL as a profile property via Appcues.identify. It lives on the Appcues user profile — usable for flow targeting and retrievable later via the Public API user profile endpoint (GET /v2/accounts/{account_id}/users/{user_id}/profile) or the flow analytics Full CSV export, which includes a column for every custom property you send to Appcues. Note that the flow events Appcues forwards to connected analytics tools carry only flow-level attributes (flowId, flowName, flowVersion, sessionId) plus the userId — not custom profile properties — so use the event’s userId as the join key, or also send subtext_url to your analytics tool directly from your own code if you want it readable there.

const subtextUrl = FS('getSession', { format: 'url.now' })
if (subtextUrl && window.Appcues) {
  window.Appcues.identify(user.id, { subtext_url: subtextUrl })
}

useEffect(() => {
  if (!user) return
  FS('setIdentity', { uid: user.id, properties: { email: user.email } })
  const subtextUrl = FS('getSession', { format: 'url.now' })
  if (subtextUrl && window.Appcues) {
    window.Appcues.identify(user.id, {
      email: user.email,
      subtext_url: subtextUrl,
    })
  }
}, [user])

Call window.Appcues.page() on route changes as usual — the identified properties persist across page calls within the session.

Don’t read FS('getSession') at module top level — it returns null until the session has started. Guard on window.Appcues being defined so you don’t call identify before the snippet has loaded. The session URL also changes on a new session and when FS('setIdentity') is called with a different uid, so re-call Appcues.identify on re-identify — the property is frozen until the next identify. Finally, don’t rely on Appcues alone to read the value back; its profile UI is limited, so retrieve it via the Public API profile endpoint or the Full CSV export (or send it to your analytics tool directly from your own code).

From signal to session

Appcues tells you a flow was skipped or abandoned at a step; it can’t show you what the user saw when the flow appeared. However you first hear about it, the path is the same: get to the subtext_url — from the user’s Appcues profile (Public API or Full CSV export), keyed by the userId on the forwarded flow event, or from your analytics tool if your app also attaches the property there — then hand it to your agent for a Detect-vs-Diagnose read.

A flow's completion rate drops after an edit

You tweaked an onboarding flow and Appcues analytics now show completion falling at a specific step.Open the Appcues flow event (e.g. flow_skipped — it may display as “Flow Skipped” in tools like Amplitude) in your connected analytics tool (Amplitude / Mixpanel / Heap, or via Segment) and note the userId on each event — or pull the flow analytics Full CSV export filtered to that step. Then look up each user’s subtext_url from their Appcues profile (the Full export column or the profile API), or from their person profile in your analytics tool if your app sends the property there directly. Grab several from users who skipped at that step, then hand them to your agent:

After my last edit to the <flow name> onboarding flow, completion dropped at the <step> step.
Here are sessions from users who skipped there:
<PASTE 3-4 subtext_urls>

Review them. When that step appeared, did it render correctly over the right element, or is it
mis-anchored / covering something / pointing at an element that isn't there post-edit? Detect-vs-
Diagnose: the data says they skipped — what does the session show caused it? One hypothesis +
the moments.

The weekly flow health check

Your weekly health check — via the Appcues MCP (“How did all my published experiences perform this week compared to last week?”) or the Flow Analytics scoreboard — shows a key activation flow underperforming vs. last week.Take the userIds from the forwarded flow events in your analytics tool (or the flow analytics Full CSV export) for users who dropped out this week, then look up each user’s subtext_url from their Appcues profile.

This week's Appcues health check shows our activation flow underperforming. Here are sessions from
users who dropped out of it:
<PASTE subtext_urls>

Walk each one from when the flow started. Where do they fall out, and is it the same step every
time? Tell me whether the flow is broken, badly timed, or just too long, with evidence.

An A/B test on a flow is losing

Appcues A/B results show one flow variant completing worse than the other.Take the userIds for users in the losing variant from the forwarded flow events (or the flow analytics Full CSV export), then look up each user’s subtext_url from their Appcues profile.

In our Appcues A/B test, the <variant> flow is completing worse. Here are sessions from users who
saw it: <PASTE subtext_urls>

Open them and tell me what the losing variant experience was actually like — did it render cleanly,
was a step confusing, did anything break? I want to know if it's a real design loss or an
implementation bug in the variant.

For a redesign decision, ask your agent to roll the findings into one proof document (doc-create) with the flow step captured as the droppers actually saw it — the evidence for re-anchoring, re-timing, or rewriting it — then link that doc wherever your team tracks flow decisions so the completion number carries its cause.

For agents

An autonomous agent can run the whole loop against Appcues: discover the flow friction, extract the subtext_url, and hand each session to the Subtext MCP. Appcues ships an official MCP server at https://mcp.appcues.com/mcp (EU: https://mcp.eu.appcues.com/mcp), authenticated with your Appcues credentials and honoring account roles. An admin must enable it at studio.appcues.com/settings/ai-assistant (see docs.appcues.com/appcues-mcp-server). It surfaces flows, experiences, segments, goals, NPS data, events, accounts, and users — but Appcues does not publish an itemized tool-name list, so it’s best for discovering flow and NPS friction. Reading per-user attributes like subtext_url needs an extra admin toggle (“enhanced AI features”); without it, use the Public API for extraction.

Discover the friction

Use the Appcues MCP to surface flow and NPS hotspots. For per-step drop-off, the Public API (base https://api.appcues.com/v2/, with an API key + secret from Studio → Settings → Integrations → API Keys) exposes a flow analytics CSV export with a column per custom property — find the step with the largest drop. Async / bulk-event export is job-based (job_id → Get Job Status, or an emailed link that expires in ~a week), and outbound webhooks for flow/checklist events give a real-time friction stream.

Extract the session URL

Read subtext_url off the user’s complete profile via the Public API:

GET https://api.appcues.com/v2/accounts/{account_id}/users/{user_id}/profile      # "Get a user's complete profile" (EU base: https://api.eu.appcues.com)
# → custom profile attribute: subtext_url

Alternatively, pull the flow analytics Full CSV export, which includes a subtext_url column for affected users.

Hand off to Subtext

For each URL, call review-open(session_url=<subtext_url>) on the Subtext MCP, then step through the flow moment to get a Detect-vs-Diagnose read: the data says they skipped — did the step mis-anchor or mis-render, or was it just confusing?

subtext_url only round-trips if it was attached as a user profile property at capture time (see Attach the session URL). Without the enhanced AI features toggle, the MCP can’t read user attributes — use the Public API. Match your region (US vs EU) for the MCP endpoint.

Session Review overview — what your agent does once a session is open.
Install the capture snippet — required before any session URL exists to attach.

Get Started

Install by Framework

Session Review

Privacy

Integrations

Recipes

API reference

Appcues and Subtext: From a Flow to the Session

Attach the session URL

From signal to session

For agents

​Attach the session URL

​From signal to session

​For agents

​Related

Attach the session URL

From signal to session

For agents

Related