Ad-hoc retention/cohort calculation

Authorizations

SessionCookie

Parameters

Path Parameters

projectId

required

string

Request Body^required

application/json

Ad-hoc retention/cohort request. All fields optional; defaults from growth definition.

object

startEvent

string

returnEvent

string | null

granularity

string

Allowed values: day week month

cohortStart

string format: date

cohortEnd

string format: date

startDate

string format: date

endDate

string format: date

retentionDays

Array<integer>

segmentBy

string

analysisSubject

string

analysisSubjectKey

string | null

Responses

200

Retention matrix (dynamic shape). Some keys are dynamic — Two shapes discriminated by the literal segmented boolean, which is ALWAYS present. segmented=true only when body.segmentBy resolves to a valid dimension (utmSource | deviceType | visitorId | userId | sessionId | account). matrix[].retention is a DYNAMIC-KEYED map: keys are the stringified retention intervals actually requested (body.retentionDays, default [0,1,3,7,14,30]); values are percentages 0-100 rounded to 2 decimals. Keys therefore vary per request — modeled with additionalProperties: number, which is honest here. cohortDate is a date-only string “YYYY-MM-DD” (bucket start, UTC; week buckets snap to Monday, month buckets to the 1st). Matrix is sorted cohortDate DESC. headers are localized Chinese labels: index 0 is always “D0”, others are D{n}天 / D{n}周 / D{n}月 depending on granularity — same length/order as retentionDays. Errors (“起始事件不能为空”) return 400 {error: “计算失败”, detail: string}.

application/json

One of:

RetentionUnsegmented
RetentionSegmented

RetentionUnsegmented

object

segmented

required

boolean

matrix

required

Array<object>

object

cohortDate

required

Bucket start date “YYYY-MM-DD” (UTC).

string

cohortSize

required

integer

retention

required

Dynamic map: key = retention interval (stringified integer, matching retentionDays), value = percent 0-100 rounded to 2 decimals.

object

key

additional properties

number

curve

required

Array<object>

object

day

required

Retention interval (unit follows granularity).

integer

rate

required

Mean of the per-cohort rates for that interval; when no cohorts exist, 100 for day 0 and 0 otherwise.

number

headers

required

Array<string>

retentionDays

required

Array<integer>

_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

string

analysisSubjectKey

required

string

nullable

segmentBy

required

Null when the request supplied no/invalid dimension.

string

nullable

Allowed values: utmSource deviceType visitorId userId sessionId account

entityLabel

required

string

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}/retention

1
curl --request POST \
2
  --url https://retidal.com/api/projects/%3Cstring%3E/retention \
3
  --header 'Content-Type: application/json' \
4
  --cookie trackly_session=%3CYOUR_API_KEY%3E \
5
  --data '{
6
  "startEvent": "<string>",
7
  "returnEvent": "<string>",
8
  "granularity": "day",
9
  "cohortStart": "<string>",
10
  "cohortEnd": "<string>",
11
  "startDate": "<string>",
12
  "endDate": "<string>",
13
  "retentionDays": [
14
    0
15
  ],
16
  "segmentBy": "<string>",
17
  "analysisSubject": "<string>",
18
  "analysisSubjectKey": "<string>"
19
}'

1
const url = 'https://retidal.com/api/projects/%3Cstring%3E/retention';
2
const options = {
3
  method: 'POST',
4
  headers: {
5
    cookie: 'trackly_session=%3CYOUR_API_KEY%3E',
6
    'Content-Type': 'application/json'
7
  },
8
  body: '{"startEvent":"<string>","returnEvent":"<string>","granularity":"day","cohortStart":"<string>","cohortEnd":"<string>","startDate":"<string>","endDate":"<string>","retentionDays":[0],"segmentBy":"<string>","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/retention"
4

5
payload = {
6
    "startEvent": "<string>",
7
    "returnEvent": "<string>",
8
    "granularity": "day",
9
    "cohortStart": "<string>",
10
    "cohortEnd": "<string>",
11
    "startDate": "<string>",
12
    "endDate": "<string>",
13
    "retentionDays": [0],
14
    "segmentBy": "<string>",
15
    "analysisSubject": "<string>",
16
    "analysisSubjectKey": "<string>"
17
}
18
headers = {
19
    "cookie": "trackly_session=%3CYOUR_API_KEY%3E",
20
    "Content-Type": "application/json"
21
}
22

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

25
print(response.json())

1
import httpx
2
import json
3

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

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

8
payload = json.loads("{\n  \"startEvent\": \"<string>\",\n  \"returnEvent\": \"<string>\",\n  \"granularity\": \"day\",\n  \"cohortStart\": \"<string>\",\n  \"cohortEnd\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"retentionDays\": [\n    0\n  ],\n  \"segmentBy\": \"<string>\",\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/retention"
13

14
  payload := strings.NewReader("{\n  \"startEvent\": \"<string>\",\n  \"returnEvent\": \"<string>\",\n  \"granularity\": \"day\",\n  \"cohortStart\": \"<string>\",\n  \"cohortEnd\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"retentionDays\": [\n    0\n  ],\n  \"segmentBy\": \"<string>\",\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
}

200Retention matrix (dynamic shape). Some keys are dynamic — Two shapes discriminated by the literal segmented boolean, which is ALWAYS present. segmented=true only when body.segmentBy resolves to a valid dimension (utmSource | deviceType | visitorId | userId | sessionId | account). matrix[].retention is a DYNAMIC-KEYED map: keys are the stringified retention intervals actually requested (body.retentionDays, default [0,1,3,7,14,30]); values are percentages 0-100 rounded to 2 decimals. Keys therefore vary per request — modeled with additionalProperties: number, which is honest here. cohortDate is a date-only string “YYYY-MM-DD” (bucket start, UTC; week buckets snap to Monday, month buckets to the 1st). Matrix is sorted cohortDate DESC. headers are localized Chinese labels: index 0 is always “D0”, others are D{n}天 / D{n}周 / D{n}月 depending on granularity — same length/order as retentionDays. Errors (“起始事件不能为空”) return 400 {error: “计算失败”, detail: string}.

1
{
2
  "segmented": false,
3
  "_meta": {
4
    "scope": "EVENT",
5
    "requestedScope": "EVENT",
6
    "segmentBy": "utmSource"
7
  }
8
}

Ad-hoc retention/cohort calculation

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

400

Examplegenerated

Request Body^required

Example^generated