Ad-hoc funnel calculation

Authorizations

SessionCookie

Parameters

Path Parameters

projectId

required

string

Request Body^required

application/json

Ad-hoc funnel request. All fields optional; defaults filled from the saved growth definition.

object

steps

Event-name steps (>= 2 effective steps required after defaults).

Array<string>

windowHours

integer

startDate

string format: date

endDate

string format: date

filterBy

string

filterValue

string

breakdownBy

string

comparePeriod

boolean

analysisSubject

string

analysisSubjectKey

string | null

Example^generated

1
{
2
  "steps": [
3
    "example"
4
  ],
5
  "windowHours": 1,
6
  "startDate": "2026-04-15",
7
  "endDate": "2026-04-15",
8
  "filterBy": "example",
9
  "filterValue": "example",
10
  "breakdownBy": "example",
11
  "comparePeriod": true,
12
  "analysisSubject": "example",
13
  "analysisSubjectKey": "example"
14
}

Responses

200

Funnel calculation result (dynamic shape). NOTE: the funnel calculate endpoint lives in routes/analytics.ts, NOT routes/funnels.ts (funnels.ts only does CRUD on saved funnel definitions). The 200 body is one of THREE mutually exclusive shapes, selected by request body: (a) body.comparePeriod === true -> {current, previous, change, _meta} (b) body.breakdownBy is a valid dimension -> {breakdown[], _meta} (c) otherwise -> the flat funnel result spread at top level {steps[], overall, _meta} Precedence in code: comparePeriod wins over breakdownBy. breakdownBy/filterBy are normalized against a fixed dimension whitelist (utmSource | deviceType | visitorId | userId | sessionId | account); anything else -> null. Rates are percentages 0-100, NOT rounded (raw float). avgTimeToNext is in SECONDS (0 when no transitions observed). Errors (incl. “至少需要2个步骤”) return 400 {error: “计算失败”, detail: string}.

application/json

One of:

FunnelPlain

object

steps

required

Array<object>

object

step

required

1-based step index.

integer

eventName

required

string

enteredCount

required

integer

completedCount

required

Subjects reaching the NEXT step; equals enteredCount on the last step.

integer

conversionRate

required

Percent 0-100

number

dropOffRate

required

Percent 0-100

number

avgTimeToNext

required

Average seconds from this step to the next; 0 when no transitions.

number

overall

required

object

totalEntered

required

integer

totalCompleted

required

integer

conversionRate

required

Percent 0-100

number

_meta

required

object

scope

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

requestedScope

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

scopeLabel

required

Localized zh-CN label. e.g. “访客”.

string

analysisSubjectKey

required

string

nullable

filterBy

required

Null when the request supplied no/invalid dimension.

string

nullable

Allowed values: utmSource deviceType visitorId userId sessionId account

filterValue

required

string

nullable

breakdownBy

required

Null when the request supplied no/invalid dimension.

string

nullable

Allowed values: utmSource deviceType visitorId userId sessionId account

entityLabel

required

Localized zh-CN label. e.g. “访客”.

string

windowHours

required

number

400

Calculation failed / invalid body.

application/json

object

error

string

detail

string

Example^generated

1
{
2
  "error": "example",
3
  "detail": "example"
4
}

POST

/api/projects/{projectId}/funnel/calculate

1
curl --request POST \
2
  --url https://retidal.com/api/projects/%3Cstring%3E/funnel/calculate \
3
  --header 'Content-Type: application/json' \
4
  --cookie trackly_session=%3CYOUR_API_KEY%3E \
5
  --data '{
6
  "steps": [
7
    "<string>"
8
  ],
9
  "windowHours": 0,
10
  "startDate": "<string>",
11
  "endDate": "<string>",
12
  "filterBy": "<string>",
13
  "filterValue": "<string>",
14
  "breakdownBy": "<string>",
15
  "comparePeriod": true,
16
  "analysisSubject": "<string>",
17
  "analysisSubjectKey": "<string>"
18
}'

1
const url = 'https://retidal.com/api/projects/%3Cstring%3E/funnel/calculate';
2
const options = {
3
  method: 'POST',
4
  headers: {
5
    cookie: 'trackly_session=%3CYOUR_API_KEY%3E',
6
    'Content-Type': 'application/json'
7
  },
8
  body: '{"steps":["<string>"],"windowHours":0,"startDate":"<string>","endDate":"<string>","filterBy":"<string>","filterValue":"<string>","breakdownBy":"<string>","comparePeriod":true,"analysisSubject":"<string>","analysisSubjectKey":"<string>"}'
9
};
10

11
try {
12
  const response = await fetch(url, options);
13
  const data = await response.json();
14
  console.log(data);
15
} catch (error) {
16
  console.error(error);
17
}

1
import requests
2

3
url = "https://retidal.com/api/projects/%3Cstring%3E/funnel/calculate"
4

5
payload = {
6
    "steps": ["<string>"],
7
    "windowHours": 0,
8
    "startDate": "<string>",
9
    "endDate": "<string>",
10
    "filterBy": "<string>",
11
    "filterValue": "<string>",
12
    "breakdownBy": "<string>",
13
    "comparePeriod": True,
14
    "analysisSubject": "<string>",
15
    "analysisSubjectKey": "<string>"
16
}
17
headers = {
18
    "cookie": "trackly_session=%3CYOUR_API_KEY%3E",
19
    "Content-Type": "application/json"
20
}
21

22
response = requests.post(url, json=payload, headers=headers)
23

24
print(response.json())

1
import httpx
2
import json
3

4
url = "https://retidal.com/api/projects/%3Cstring%3E/funnel/calculate"
5

6
cookies = {"trackly_session": "<YOUR_API_KEY>"}
7

8
payload = json.loads("{\n  \"steps\": [\n    \"<string>\"\n  ],\n  \"windowHours\": 0,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"filterBy\": \"<string>\",\n  \"filterValue\": \"<string>\",\n  \"breakdownBy\": \"<string>\",\n  \"comparePeriod\": true,\n  \"analysisSubject\": \"<string>\",\n  \"analysisSubjectKey\": \"<string>\"\n}")
9

10
response = httpx.post(url, cookies=cookies, json=payload)
11

12
print(response.json())

1
package main
2

3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io"
8
)
9

10
func main() {
11

12
  url := "https://retidal.com/api/projects/%3Cstring%3E/funnel/calculate"
13

14
  payload := strings.NewReader("{\n  \"steps\": [\n    \"<string>\"\n  ],\n  \"windowHours\": 0,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"filterBy\": \"<string>\",\n  \"filterValue\": \"<string>\",\n  \"breakdownBy\": \"<string>\",\n  \"comparePeriod\": true,\n  \"analysisSubject\": \"<string>\",\n  \"analysisSubjectKey\": \"<string>\"\n}")
15

16
  req, _ := http.NewRequest("POST", url, payload)
17

18
  req.Header.Add("cookie", "trackly_session=%3CYOUR_API_KEY%3E")
19
  req.Header.Add("Content-Type", "application/json")
20

21
  res, _ := http.DefaultClient.Do(req)
22

23
  defer res.Body.Close()
24
  body, _ := io.ReadAll(res.Body)
25

26
  fmt.Println(res)
27
  fmt.Println(string(body))
28

29
}

200Funnel calculation result (dynamic shape). NOTE: the funnel calculate endpoint lives in routes/analytics.ts, NOT routes/funnels.ts (funnels.ts only does CRUD on saved funnel definitions). The 200 body is one of THREE mutually exclusive shapes, selected by request body: (a) body.comparePeriod === true -> {current, previous, change, _meta} (b) body.breakdownBy is a valid dimension -> {breakdown[], _meta} (c) otherwise -> the flat funnel result spread at top level {steps[], overall, _meta} Precedence in code: comparePeriod wins over breakdownBy. breakdownBy / filterBy are normalized against a fixed dimension whitelist (utmSource | deviceType | visitorId | userId | sessionId | account); anything else -> null. Rates are percentages 0-100, NOT rounded (raw float). avgTimeToNext is in SECONDS (0 when no transitions observed). Errors (incl. “至少需要2个步骤”) return 400 {error: “计算失败”, detail: string}.

1
{
2
  "_meta": {
3
    "scope": "EVENT",
4
    "requestedScope": "EVENT",
5
    "filterBy": "utmSource",
6
    "breakdownBy": "utmSource"
7
  }
8
}

Ad-hoc funnel calculation

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Examplegenerated

Responses

200

400

Examplegenerated

Request Body^required

Example^generated

Example^generated