# Measure a verified three-step signup funnel

> Map three ordered lifecycle events to live project signals, run the canonical funnel blueprint, and explain drop-offs without inventing causes or benchmarks.

## Agent adaptation contract

- Canonical human page: https://agentry.sh/workflows/signup-funnel
- Execution mode: on_demand
- Immutable automation template: none
- Applies to: b2c-saas, b2b-saas, devtools-api, single-purchase, enterprise-sales
- Required example events: signup_started, signup_completed, activation_completed
- Required Agentry resources: signal_map, onboarding_state, query_blueprints
- Do not use when:
  - Do not use the example event names when the project's saved signal map defines different lifecycle events.
  - Do not interpret missing or synthetic-only events as real user drop-off.
  - Do not claim industry benchmarks, time-to-next-step, causes, or four-step results from the three-count blueprint.
- Ask before using:
  - Which three observed events define entry, completed signup, and meaningful activation in their required order?
  - Which stable identity links the events, and can anonymous-to-known identity transitions be joined without double counting?
  - What exact lookback window and audience should the funnel cover?

This is an adaptable workflow example, not an API recipe. Map event and property names to the project's saved signal map, require status: "verified" from GET /v1/projects/:project_id/onboarding, and confirm the required signals through live event/property metadata and rows. Fetch current OpenAPI or query-blueprint details before making calls. Do not infer unattended authority from this page.

## Why this matters

A funnel is only as trustworthy as its event mapping and identity continuity.
Running a plausible query against guessed event names can turn missing
instrumentation into a false product conclusion.

Agentry's `funnel_3_step` blueprint answers a deliberately narrow question: how
many distinct identities completed step 1, then step 2 after step 1, then step 3
after step 2 during the selected lookback. It returns three counts. The agent
calculates drop-off percentages and labels explanations as hypotheses.

## What you get

- Three approved, observed events mapped to the product's actual lifecycle
- Canonical ordered-funnel counts for a disclosed lookback window
- Step-to-step and overall conversion calculated from those counts
- Instrumentation gaps, identity caveats, and hypotheses kept separate from evidence

## Walk through it

**You:**
> Where do users drop between signup and first value?

**Agent:**
> I will use the saved lifecycle definition and observed event names, not the
> example names from this page.

```http
GET /v1/projects/:project_id/signal-map
GET /v1/projects/:project_id/onboarding
# Require status: "verified"; use live event/property reads for the selected signals.
GET /v1/projects/:project_id/event-names
```

```json
{
  "server_emitted": [],
  "analytics_events": [
    { "event": "signup_started", "count": 1840, "last_seen": 1783651200 },
    { "event": "signup_email_verified", "count": 1240, "last_seen": 1783651210 },
    { "event": "first_project_created", "count": 720, "last_seen": 1783651250 }
  ],
  "wildcards": []
}
```

After confirming these events match the approved lifecycle and have real
traffic, fetch and run the current blueprint:

```http
GET /v1/query-blueprints/funnel_3_step
POST /v1/projects/:project_id/query-blueprints/funnel_3_step/run
```

```text
Params:
  step1: signup_started
  step2: signup_email_verified
  step3: first_project_created
  days: 30
```

```json
{
  "rows": [
    {
      "step1_count": 1840,
      "step2_count": 1240,
      "step3_count": 720
    }
  ]
}
```

From these counts, step 1→2 conversion is 67.4%, step 2→3 is 58.1%, and
step 1→3 is 39.1%. The data identifies where measured loss is largest; it does
not explain why.

## The output

```text
Signup funnel — last 30 days

signup_started             1,840  100.0%
  ↳ drop to step 2           600   32.6%
signup_email_verified      1,240   67.4%
  ↳ drop to step 3           520   41.9%
first_project_created        720   39.1% of entry

Evidence caveats
- <identity transition, sampling, delayed ingestion, or missing event>

Hypotheses to investigate
- <possible explanation, explicitly labelled>
```

If a public view is explicitly requested, publish only the same approved
`funnel_3_step` blueprint with the same params and use the returned
`public_url`. Publication is a separate reviewed action, not an automatic end
of funnel analysis.

## Setting it up

Send the lifecycle events through `POST /v1/analytics/` using the public browser
or trusted server credential appropriate to the event source. Use one stable
`distinct_id` across all steps. If signup changes an anonymous identifier into
a known user identifier, implement and verify the product's identity-linking
strategy before trusting the funnel.

Do not add events merely to satisfy this page. Start from the business question,
define what completed signup and first value mean in this product, then verify
those signals through the install plan and live proof gates.

## Variations

- *"Compare the same three-step funnel across two exact adjacent periods."*
- *"Segment the funnel by an observed plan or acquisition property."*
- *"Tell me which step is not answerable and the exact telemetry needed."*
- *"Render weekly-funnel-review@2.0.0 with these approved events in exact order, but leave it disabled."*