# Funnels, user paths and feature usage

> Lampwick turns the requests of signed-in users into funnels, user paths and usage per route, and alerts when a funnel step's conversion drops after a deploy.

Lampwick builds funnels, user paths and usage per route from the requests it already receives. There is nothing to add to your app: no tracking script, no events to name. It counts **signed-in users** only, because a request needs a user id to be followed to the next one.

## Requirements

- Requests with a user. The [Laravel package](/docs/laravel/) sends Laravel's authenticated user; with [OpenTelemetry](/docs/opentelemetry/), set `enduser.id` on the request span.
- Funnels per project: Free 1, Pro 3, Team 20, Business unlimited.
- Funnel alerts: the Team plan and up.

Numbers update hourly. A new funnel is filled from the data Lampwick keeps (your plan's retention) within a few minutes.

## Create a funnel

1. Open the project and go to **Funnels** in the sidebar.
2. Click **New funnel**, give it a name and pick 2 to 8 routes in order, for example `GET /cart`, `POST /checkout`, `GET /orders/{order}`. The routes are listed by traffic of the last 7 days.
3. Pick the **Conversion window**: how long a user has from the first step to the last (7 days by default).
4. Click **Create funnel**.

The funnel's page says "Lampwick is counting this funnel" while it fills the funnel from the kept requests. After a few minutes the **Steps** card shows the users per step. If it stays empty, see [Troubleshooting](#troubleshooting).

A user enters the funnel with a request to the first step and moves on with a request to the next step, in that order, within the window. Requests to other routes in between don't matter. A request that answers with a 5xx doesn't count as reaching a step. After a user completes the funnel, or the window runs out, their next request to the first step starts a new attempt.

From the API or an agent, pass the routes as text:

```bash
curl -X POST https://app.lampwick.dev/api/v1/projects/42/funnels \
  -H "Authorization: Bearer $LAMPWICK_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Checkout", "steps": "GET /cart → POST /checkout → GET /orders/{order}"}'
```

## Read a funnel

The funnel's page shows, for the users who entered in the range:

| Section | What it shows |
|---|---|
| **Steps** | Users who reached each step, the share of the previous step and of the start, how many dropped off, the median time from the previous step, and 5xx on the step's route. |
| **Problems on each step** | How users who hit a server error, an exception or a slow response (slower than the route's p95 over the 7 days before) on a step went on, against everyone else at that step. |
| **Why users drop off** | For the step that loses the most users: the top issues and server errors on its routes. |
| **Conversion by deploy** | Users grouped by the deploy that was live when they entered. Needs [deploys](/docs/deploys/). |

"Can still complete" counts users who entered less than the conversion window ago and haven't reached the last step yet. Their numbers can still grow, so the conversion of the last days, and of a deploy that went out recently, looks lower than it will end up.

## Funnel alerts

Click **Turn on alerts** on a funnel to tell the team when a step's conversion drops. Every hour Lampwick compares, per step, how many users went on to the next step within an hour, for users who reached the step in the last 6 hours, against the 7 days before. It alerts only when all of these hold:

- at least 30 users reached the step recently and 100 in the 7 days before,
- conversion dropped by at least 10 percentage points and by at least a quarter,
- the drop is unlikely to be chance (a one-sided two-proportion z-test, z of 3 or more).

The alert says which step dropped, since when and by how much, and names the deploy that went live in the day before, the 5xx and the top issue on the step's routes. For example:

> **Conversion dropped: Checkout, step 5 (POST /checkout)**
> Since 08:00 UTC, 41% of the 52 users who reached GET /cart went on to POST /checkout (against 72% in the 7 days before). Deploy v2026.11.10 went live shortly before. 15 × 5xx on these steps. Top issue: #5 App\Exceptions\PaymentFailedException.

On a plan without funnel alerts (after a downgrade, say), the funnel keeps its setting but the checks pause; the funnel's page shows **Alerts paused**. It goes to the whole team by push notification, e-mail and [alert channels](/docs/alerts/), at most once per step per day. On the iPhone app it follows the **Issues** notification switch.

## User paths

**User paths** shows, for one route, where signed-in users came from and where they went next in the same session, where sessions started and ended, and the most common 3-step flows from and through it. A session ends after 30 minutes without a request. Open it from **Funnels** → **User paths**, from a step of a funnel, or from a route's page under **Requests**.

## Feature usage

**Requests** shows per route the distinct signed-in users per day and their share of the day's active users, with an arrow when the share changed against the period before. Two tabs:

- **New in a release**: routes that first answered after Lampwick started receiving data, with the release they came in and their adoption per day since.
- **Not hit in 7 days**: routes Lampwick has seen within your retention that had no request since. Routes that never had a request aren't known to Lampwick.

Users per day are counted after the day ends (UTC), so today shows up tomorrow.

## For agents (MCP)

`findDropOffs` answers "where do users drop off, and why" in one call: for a funnel, the step that loses the most users with its conversion, the impact of errors and slow responses, the top issues, server errors and slowest requests on it; for a start route such as `GET /cart`, the most common path from it and where sessions end. `createFunnel`, `getFunnel`, `getRoutePaths` and `listRouteUsage` are tools too. See [MCP](/docs/mcp/).

## Troubleshooting

| Message or symptom | Cause and fix |
|---|---|
| `step 2: no route "POST /chekout" in this project` | The route must have had a request within your retention. Copy the label from **Requests**. |
| `a project can have 1 funnel on the Free plan` | Delete a funnel or upgrade the team's plan. |
| `the Free plan doesn't include funnel alerts` | Alerts need the Team plan. |
| The funnel shows no users | Only signed-in users count. Check that **Users** lists users for the project; the **Funnels** page also says so when the project has no requests with a user. |
| Conversion looks low for the last day | Users who entered recently may still complete within the conversion window. Look at a range longer than the window. |