Funnel Analytics

Overview

Funnels track multi-step user journeys to analyze conversion rates and identify drop-off points. Create funnels based on page views or custom events.

Funnel Endpoints

Funnel analytics use a separate set of RPC endpoints managed through the AI tools system. These endpoints are not part of the standard query API.

List Funnels

Retrieve all funnels configured for a website.

curl -X POST 'https://api.databuddy.com/rpc/funnels/list' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "web_abc123"
  }'

Request Body:

websiteId

string

required

The website ID to list funnels for.

Response:

funnels

array

Array of funnel objects containing:

id: Funnel ID
name: Funnel name
description: Funnel description
steps: Array of funnel steps
filters: Applied filters
createdAt: Creation timestamp

count

number

Total number of funnels.

Get Funnel by ID

Retrieve details for a specific funnel.

curl -X POST 'https://api.databuddy.com/rpc/funnels/getById' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "funnel_xyz789",
    "websiteId": "web_abc123"
  }'

Request Body:

string

required

The funnel ID.

websiteId

string

required

The website ID.

Get Funnel Analytics

Retrieve conversion data and metrics for a funnel.

curl -X POST 'https://api.databuddy.com/rpc/funnels/getAnalytics' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "funnelId": "funnel_xyz789",
    "websiteId": "web_abc123",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'

Request Body:

funnelId

string

required

The funnel ID to analyze.

websiteId

string

required

The website ID.

startDate

string

Start date in YYYY-MM-DD format. Defaults to 30 days ago.

endDate

string

End date in YYYY-MM-DD format. Defaults to today.

Response: The response includes step-by-step conversion metrics:

steps

array

Array of funnel steps with metrics:

step_number: Step position (1-based)
step_name: Human-readable step name
users_entered: Users who reached this step
users_completed: Users who completed this step and moved forward
conversion_rate: Percentage who proceeded to next step
drop_off_rate: Percentage who dropped off at this step
time_to_complete: Average time to complete this step

overall_conversion_rate

number

Percentage of users who completed the entire funnel.

total_users_entered

number

Number of users who entered the funnel at step 1.

total_users_completed

number

Number of users who completed all steps.

Get Funnel Analytics by Referrer

Analyze funnel performance segmented by traffic source.

curl -X POST 'https://api.databuddy.com/rpc/funnels/getAnalyticsByReferrer' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "funnelId": "funnel_xyz789",
    "websiteId": "web_abc123",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'

Request Body: Same as getAnalytics Response:

referrers

array

Array of referrer sources with funnel metrics:

referrer: Referrer domain or source
users_entered: Users from this source
users_completed: Users who completed the funnel
conversion_rate: Source-specific conversion rate
steps: Per-step metrics for this source

Create Funnel

Create a new funnel to track a conversion path.

curl -X POST 'https://api.databuddy.com/rpc/funnels/create' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "web_abc123",
    "name": "Signup Funnel",
    "description": "Track user signup process",
    "steps": [
      {
        "type": "PAGE_VIEW",
        "target": "/signup",
        "name": "Visit Signup Page"
      },
      {
        "type": "EVENT",
        "target": "form_submit",
        "name": "Submit Form"
      },
      {
        "type": "PAGE_VIEW",
        "target": "/welcome",
        "name": "Welcome Page"
      }
    ],
    "filters": [
      {
        "field": "country",
        "operator": "equals",
        "value": "US"
      }
    ],
    "ignoreHistoricData": false
  }'

Request Body:

websiteId

string

required

The website ID.

name

string

required

Funnel name (1-100 characters).

description

string

Optional funnel description.

steps

array

required

Array of 2-10 funnel steps. Each step must include:

type: Step type (PAGE_VIEW, EVENT, or CUSTOM)
target: Page path (for PAGE_VIEW) or event name (for EVENT)
name: Human-readable step name
conditions: Optional additional conditions (object)

filters

array

Optional array of filters to apply to the funnel:

field: Filter field name
operator: Filter operator (equals, contains, not_equals, in, not_in)
value: Filter value (string or array of strings)

ignoreHistoricData

boolean

default:"false"

If true, only tracks data from the funnel creation date forward.

Response:

success

boolean

Whether the funnel was created successfully.

funnel

object

The created funnel object with all details and assigned ID.

Funnel Step Types

PAGE_VIEW Steps

Track when users visit specific pages:

{
  "type": "PAGE_VIEW",
  "target": "/pricing",
  "name": "View Pricing Page"
}

Matches exact page paths
Path normalization automatically applied (trailing slashes removed)
Can use wildcards in target (e.g., /blog/*)

EVENT Steps

Track when custom events are triggered:

{
  "type": "EVENT",
  "target": "add_to_cart",
  "name": "Add Product to Cart",
  "conditions": {
    "product_category": "premium"
  }
}

Matches custom event names
Optional conditions filter events by property values

CUSTOM Steps

Advanced step definitions with custom logic:

{
  "type": "CUSTOM",
  "target": "custom_condition",
  "name": "Custom Step",
  "conditions": {
    "sql": "custom_field = 'value'"
  }
}

Funnel Analysis Features

Conversion Tracking

Calculate conversion rates between each step
Identify highest drop-off points
Track overall funnel completion rate
Measure time taken between steps

Segmentation

Break down conversions by referrer/source
Apply filters to analyze specific user segments
Compare performance across device types, countries, etc.

Time-based Analysis

Specify date ranges for analysis
Compare funnel performance across different periods
Track trends over time

Best Practices

Keep funnels focused: 2-5 steps is optimal. Very long funnels become harder to analyze.
Order matters: Steps must be defined in the expected user journey order.
Use clear naming: Step names should clearly describe the user action.
Start broad: Begin with a simple funnel, then add filters to segment.
Test your events: Verify custom events are firing correctly before creating event-based steps.
Monitor regularly: Check funnel analytics weekly to catch conversion issues early.

Example: E-commerce Checkout Funnel

{
  "websiteId": "web_abc123",
  "name": "Checkout Funnel",
  "description": "Track the complete purchase flow from cart to confirmation",
  "steps": [
    {
      "type": "PAGE_VIEW",
      "target": "/cart",
      "name": "View Cart"
    },
    {
      "type": "PAGE_VIEW",
      "target": "/checkout",
      "name": "Start Checkout"
    },
    {
      "type": "EVENT",
      "target": "payment_info_entered",
      "name": "Enter Payment Info"
    },
    {
      "type": "EVENT",
      "target": "order_completed",
      "name": "Complete Order"
    },
    {
      "type": "PAGE_VIEW",
      "target": "/order-confirmation",
      "name": "View Confirmation"
    }
  ],
  "filters": [
    {
      "field": "device_type",
      "operator": "in",
      "value": ["desktop", "mobile"]
    }
  ]
}

Notes

Funnels are evaluated in real-time as users progress through steps
A user can be counted multiple times if they restart the funnel
Steps must occur in order; skipping steps counts as a drop-off
Maximum 10 steps per funnel
Filters apply to all steps in the funnel
Historical data analysis depends on the ignoreHistoricData setting

Overview

Events API

Analytics API

Projects API

Links API

Uptime API

SDK Reference

Overview

Funnel Endpoints

List Funnels

Get Funnel by ID

Get Funnel Analytics

Get Funnel Analytics by Referrer

Create Funnel

Funnel Step Types

PAGE_VIEW Steps

EVENT Steps

CUSTOM Steps

Funnel Analysis Features

Conversion Tracking

Segmentation

Time-based Analysis

Best Practices

Example: E-commerce Checkout Funnel

Notes

Overview

Events API

Analytics API

Projects API

Links API

Uptime API

SDK Reference

​Overview

​Funnel Endpoints

​List Funnels

​Get Funnel by ID

​Get Funnel Analytics

​Get Funnel Analytics by Referrer

​Create Funnel

​Funnel Step Types

​PAGE_VIEW Steps

​EVENT Steps

​CUSTOM Steps

​Funnel Analysis Features

​Conversion Tracking

​Segmentation

​Time-based Analysis

​Best Practices

​Example: E-commerce Checkout Funnel

​Notes

Overview

Funnel Endpoints

List Funnels

Get Funnel by ID

Get Funnel Analytics

Get Funnel Analytics by Referrer

Create Funnel

Funnel Step Types

PAGE_VIEW Steps

EVENT Steps

CUSTOM Steps

Funnel Analysis Features

Conversion Tracking

Segmentation

Time-based Analysis

Best Practices

Example: E-commerce Checkout Funnel

Notes