Funnel Breakdown

Return funnel performance grouped by the selected breakdown dimensions.

curl -X GET "https://api.beacon.hard.al/v1/funnels/123e4567-e89b-12d3-a456-426614174000/breakdown?tenantId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&breakdownLimit=example_string&breakdownOffset=example_string&breakdownSearch=example_string&breakdownSortBy=share&breakdownSortStep=example_string&breakdownSortDirection=asc&breakdownKeys=example_string" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests
import json

url = "https://api.beacon.hard.al/v1/funnels/123e4567-e89b-12d3-a456-426614174000/breakdown?tenantId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&breakdownLimit=example_string&breakdownOffset=example_string&breakdownSearch=example_string&breakdownSortBy=share&breakdownSortStep=example_string&breakdownSortDirection=asc&breakdownKeys=example_string"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://api.beacon.hard.al/v1/funnels/123e4567-e89b-12d3-a456-426614174000/breakdown?tenantId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&breakdownLimit=example_string&breakdownOffset=example_string&breakdownSearch=example_string&breakdownSortBy=share&breakdownSortStep=example_string&breakdownSortDirection=asc&breakdownKeys=example_string", {
  method: "GET",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
)

func main() {

    req, err := http.NewRequest("GET", "https://api.beacon.hard.al/v1/funnels/123e4567-e89b-12d3-a456-426614174000/breakdown?tenantId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&breakdownLimit=example_string&breakdownOffset=example_string&breakdownSearch=example_string&breakdownSortBy=share&breakdownSortStep=example_string&breakdownSortDirection=asc&breakdownKeys=example_string", nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://api.beacon.hard.al/v1/funnels/123e4567-e89b-12d3-a456-426614174000/breakdown?tenantId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&breakdownLimit=example_string&breakdownOffset=example_string&breakdownSearch=example_string&breakdownSortBy=share&breakdownSortStep=example_string&breakdownSortDirection=asc&breakdownKeys=example_string')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

{
  "success": true,
  "data": {
    "range": {
      "startDate": "2026-10-01",
      "endDate": "2026-10-07",
      "timezone": "Europe/Istanbul"
    },
    "breakdownTable": {
      "columns": {
        "breakdowns": [
          {
            "breakdownKey": "channel",
            "breakdownLabel": "Channel"
          }
        ],
        "steps": [
          {
            "stepOrder": 1,
            "stepName": "/pricing"
          },
          {
            "stepOrder": 2,
            "stepName": "add_to_cart"
          },
          {
            "stepOrder": 3,
            "stepName": "purchase"
          }
        ]
      },
      "totalRow": {
        "breakdownValues": {},
        "share": 100,
        "stepCounts": [
          940,
          235,
          113
        ],
        "stepRates": [
          100,
          100,
          100
        ]
      },
      "rows": [
        {
          "breakdownValues": {
            "channel": "Direct"
          },
          "share": 40,
          "stepCounts": [
            376,
            94,
            45
          ],
          "stepRates": [
            40,
            40,
            39.82
          ]
        },
        {
          "breakdownValues": {
            "channel": "OrganicSearch"
          },
          "share": 35,
          "stepCounts": [
            329,
            82,
            40
          ],
          "stepRates": [
            35,
            34.89,
            35.4
          ]
        },
        {
          "breakdownValues": {
            "channel": "PaidSearch"
          },
          "share": 25,
          "stepCounts": [
            235,
            59,
            28
          ],
          "stepRates": [
            25,
            25.11,
            24.78
          ]
        }
      ],
      "pagination": {
        "limit": 25,
        "offset": 0,
        "total": 3
      },
      "sort": {
        "sortBy": "share",
        "sortStep": null,
        "sortDirection": "desc"
      },
      "search": ""
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-required",
    "message": "tenant-required"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "validation-error",
    "message": "Validation failed for 'timeframe': timeframe must be one of: today, yesterday, last7days, last30days, custom",
    "details": {
      "field": "timeframe",
      "message": "timeframe must be one of: today, yesterday, last7days, last30days, custom"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "bearer-required",
    "message": "bearer-required"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "invalid-credential",
    "message": "invalid-credential"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "credential-revoked",
    "message": "credential-revoked"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "credential-expired",
    "message": "credential-expired"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-not-granted",
    "message": "tenant-not-granted",
    "details": {
      "tenantId": "2f1c7c3e-6c1a-4f1e-9b7a-2d8e4c1a9f10"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "insufficient-scope",
    "message": "insufficient-scope",
    "details": {
      "required": "reports:read"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-not-found",
    "message": "tenant-not-found",
    "details": {
      "tenantId": "2f1c7c3e-6c1a-4f1e-9b7a-2d8e4c1a9f10"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "funnel-not-found",
    "message": "funnel-not-found",
    "details": {
      "funnelId": "c41d9f0a-3b76-4e21-a5c8-9e2f7d1b6a34"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "rate-limited",
    "message": "rate-limited",
    "details": {
      "retryAfterSeconds": 30
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/funnels/{funnelId}/breakdown",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

GET

/v1/funnels/{funnelId}/breakdown

GET

Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token

Bearer Tokenstring

Required

OAuth access token (token exchange) or organization API key.

path

funnelIdstring

Required

UUID of a saved funnel, as returned by GET /v1/funnels.

Format: uuid

query

tenantIdstring

Required

UUID of the tenant to report on. Send it exactly once. GET /v1/workspace/access lists the tenants this credential can read.

Format: uuid

query

timeframestring

Reporting period. The presets today, yesterday, last7days and last30days cover whole calendar days ending today in the request timezone; last7days is today and the six days before it. Use custom together with startDate and endDate. Defaults to the last 30 days.

query

startDatestring

First day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom, together with endDate.

query

endDatestring

Last day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom; it must not be before startDate.

query

timezonestring

IANA time zone name such as Europe/Istanbul or America/New_York. It sets the calendar-day boundaries of the period and of the time buckets. Defaults to Europe/Istanbul.

Min length: 1 • Max length: 100

query

breakdownLimitstring

Maximum number of breakdown rows to return, 1 to 100. Defaults to 25.

Min: 1 • Max: 100

query

breakdownOffsetstring

Number of breakdown rows to skip, 0 to 10000. Defaults to 0.

Min: 0 • Max: 10000

query

breakdownSearchstring

Only return rows whose breakdown value contains this text. Case-insensitive.

query

breakdownSortBystring

share sorts by the share of funnel entries, breakdown alphabetically and stepCount by the count of the step in breakdownSortStep. Defaults to share.

query

breakdownSortStepstring

Step number to sort by when breakdownSortBy=stepCount, from 1 to the number of steps. Defaults to 1.

Min: 1 • Max: 10

query

breakdownSortDirectionstring

asc or desc. Defaults to desc.

query

breakdownKeysstring

Comma-separated list of up to two dimensions: source, medium, channel, country, city, device, browser, os. With two keys the second is nested under the first in children. Defaults to the breakdowns saved with the funnel.

Request Preview

Response

Response will appear here after sending the request

Authentication

header

Authorizationstring

Required

Bearer token. OAuth access token (token exchange) or organization API key.

Path Parameters

funnelIdstring

Required

UUID of a saved funnel, as returned by GET /v1/funnels.

Query Parameters

tenantIdstring

Required

UUID of the tenant to report on. Send it exactly once. GET /v1/workspace/access lists the tenants this credential can read.

timeframestring

startDatestring

First day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom, together with endDate.

endDatestring

Last day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom; it must not be before startDate.

timezonestring

IANA time zone name such as Europe/Istanbul or America/New_York. It sets the calendar-day boundaries of the period and of the time buckets. Defaults to Europe/Istanbul.

breakdownLimitstring

Maximum number of breakdown rows to return, 1 to 100. Defaults to 25.

breakdownOffsetstring

Number of breakdown rows to skip, 0 to 10000. Defaults to 0.

breakdownSearchstring

Only return rows whose breakdown value contains this text. Case-insensitive.

breakdownSortBystring

share sorts by the share of funnel entries, breakdown alphabetically and stepCount by the count of the step in breakdownSortStep. Defaults to share.

breakdownSortStepstring

Step number to sort by when breakdownSortBy=stepCount, from 1 to the number of steps. Defaults to 1.

breakdownSortDirectionstring

asc or desc. Defaults to desc.

breakdownKeysstring

Responses

successboolean

Required

Allowed values:true

dataobject

Required

timestampstring

Required

pathstring

Required

requestIdstring

Required

Was this page helpful?