> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Appcues and Subtext: From a Flow to the Session

> Attach the Subtext session URL to Appcues, then jump from any flow signal — a skipped step, an abandoned onboarding, a losing A/B variant — straight into the user's real 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.

<Note>
  This guide assumes the [Subtext capture snippet](/docs/install/overview) is installed and capturing sessions, and the Appcues Web SDK snippet is loaded (`window.Appcues` is available).
</Note>

## 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.

<CodeGroup>
  ```js analytics.js theme={null}
  const subtextUrl = FS('getSession', { format: 'url.now' })
  if (subtextUrl && window.Appcues) {
    window.Appcues.identify(user.id, { subtext_url: subtextUrl })
  }
  ```

  ```tsx React theme={null}
  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])
  ```
</CodeGroup>

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

<Warning>
  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).
</Warning>

## 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.

<AccordionGroup>
  <Accordion title="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:

    ```text theme={null}
    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.
    ```
  </Accordion>

  <Accordion title="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 `userId`s 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.

    ```text theme={null}
    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.
    ```
  </Accordion>

  <Accordion title="An A/B test on a flow is losing">
    Appcues A/B results show one flow variant completing worse than the other.

    Take the `userId`s 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.

    ```text theme={null}
    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.
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  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.
</Tip>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Extract the session URL">
    Read `subtext_url` off the user's complete profile via the Public API:

    ```text theme={null}
    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.
  </Step>

  <Step title="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?
  </Step>
</Steps>

<Note>
  `subtext_url` only round-trips if it was attached as a user profile property at capture time (see [Attach the session URL](#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.
</Note>

## Related

* [Session Review overview](/docs/session-review/overview) — what your agent does once a session is open.
* [Install the capture snippet](/docs/install/overview) — required before any session URL exists to attach.