Skip to content

Build a funnel ​

A funnel orders existing goals into steps and measures how many sessions reach each one. Funnels belong to an analytics group, because a journey can cross distributions — for example, an embedded form followed by a thank-you page on a site.

Funnel creation is not available in the web console. Use an agent, the CLI, or the API, then read the result in Analytics → Conversions → Funnels. You also need the goal ids for every step. A type of data cannot be a funnel member.

1. Put the distributions in a group ​

For a journey on one distribution, an agent can use its implicit group. For a journey that crosses distributions, create an explicit group.

text
Create an analytics group called "Acme signup journey" with the marketing
site and signup embed distributions.
bash
edge api POST /v1/groups --input - <<'EOF'
{
        "slug": "acme-signup",
        "display_name": "Acme signup journey",
        "distribution_ids": [
          "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
          "92ab45ce-61d8-4f23-a9b0-cc3128e7d456"
        ]
      }
EOF
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/groups \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "slug": "acme-signup",
        "display_name": "Acme signup journey",
        "distribution_ids": [
          "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
          "92ab45ce-61d8-4f23-a9b0-cc3128e7d456"
        ]
      }'

The agent runs edge_group_create. Every member must belong to the current workspace.

2. Define the steps and window ​

Each step references a goal on one group member. A funnel requires 2–8 steps.

Choose:

  • sequential — intervening events are allowed as long as the steps occur in order.
  • strict — the defined path must be followed without an intervening disqualifying step.
  • session — a fixed 30-minute conversion window.
  • fixed — a positive duration such as 24 hours or 7 days.

Cross-distribution steps and fixed windows longer than 24 hours require decorated links so Edge can carry journey identity forward. Edge marks those steps with requires_decoration; do not treat an undecorated cross-site zero as evidence that nobody converted.

Check a candidate definition before saving it:

text
Check a sequential signup funnel in the Acme signup group: pricing viewed,
then signup completed, within one session. Exclude bots.
bash
edge api POST /v1/groups/6a317fca-7df0-41e2-a768-39a2bf51d807/funnels/check --input - <<'EOF'
{
        "mode": "sequential",
        "window_kind": "session",
        "interval": "30 minutes",
        "range": { "preset": "last_28_days" },
        "include_bots": false,
        "steps": [
          {
            "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
            "goal_id": "2aa61840-c3dc-42ec-9672-f5b872cd71e0"
          },
          {
            "distribution_id": "92ab45ce-61d8-4f23-a9b0-cc3128e7d456",
            "goal_id": "70a113ee-bddc-41b7-9814-674518735e23"
          }
        ]
      }
EOF
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/groups/6a317fca-7df0-41e2-a768-39a2bf51d807/funnels/check \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "mode": "sequential",
        "window_kind": "session",
        "interval": "30 minutes",
        "range": { "preset": "last_28_days" },
        "include_bots": false,
        "steps": [
          {
            "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
            "goal_id": "2aa61840-c3dc-42ec-9672-f5b872cd71e0"
          },
          {
            "distribution_id": "92ab45ce-61d8-4f23-a9b0-cc3128e7d456",
            "goal_id": "70a113ee-bddc-41b7-9814-674518735e23"
          }
        ]
      }'

The agent runs edge_funnel_check. Checking validates membership, content capabilities, goal ownership and property filters without saving the funnel.

3. Save the funnel ​

Send the same definition to the group's funnels collection with a slug and display name:

text
Save that checked funnel as "Pricing to signup" with the slug pricing-to-signup.
bash
edge api POST /v1/groups/6a317fca-7df0-41e2-a768-39a2bf51d807/funnels --input - <<'EOF'
{
        "slug": "pricing-to-signup",
        "display_name": "Pricing to signup",
        "mode": "sequential",
        "window_kind": "session",
        "interval": "30 minutes",
        "steps": [
          {
            "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
            "goal_id": "2aa61840-c3dc-42ec-9672-f5b872cd71e0"
          },
          {
            "distribution_id": "92ab45ce-61d8-4f23-a9b0-cc3128e7d456",
            "goal_id": "70a113ee-bddc-41b7-9814-674518735e23"
          }
        ]
      }
EOF
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/groups/6a317fca-7df0-41e2-a768-39a2bf51d807/funnels \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "slug": "pricing-to-signup",
        "display_name": "Pricing to signup",
        "mode": "sequential",
        "window_kind": "session",
        "interval": "30 minutes",
        "steps": [
          {
            "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
            "goal_id": "2aa61840-c3dc-42ec-9672-f5b872cd71e0"
          },
          {
            "distribution_id": "92ab45ce-61d8-4f23-a9b0-cc3128e7d456",
            "goal_id": "70a113ee-bddc-41b7-9814-674518735e23"
          }
        ]
      }'

The agent runs edge_funnel_create.

4. Query and interpret it ​

Use edge_funnel_query or POST /v1/groups/{group_id}/funnels/{funnel_id}/query. Query modes are snapshot, trend, step_trend and compare.

The first step is the entered population. Each later step shows completions and drop-off from that population. Bots are excluded unless you explicitly include them.

Changing a funnel definition increments its version and can change historical results inside the retention window. Archive definitions you no longer want to use rather than reusing their slug for a different journey.

Next ​