Get the project growth definition + templates + candidate events

Authorizations

SessionCookie

Parameters

Path Parameters

projectId

required

string

Responses

200

{ definition, draft, templates, analysisSubjects, events }. Some keys are dynamic — Envelope is FIXED: {definition, draft, templates, analysisSubjects, events}. definition is null when the project has never saved one. definition’s own columns are a fixed schema, BUT its four JSON columns (northStarMetric / aarrrStages / defaultFunnel / defaultRetention) are typed only as Record<string,unknown> / Array<Record<string,unknown>> in the repo layer and are stored as raw JSON text columns. On the WRITE path only aarrrStages is structurally validated (stageSchema, exactly 5 items) — the other three go through z.record(z.string(), z.unknown()) and are stored verbatim. The shapes the app itself writes (from createGrowthDefinitionDraft) are documented below as the observed/typical shape, but the API cannot guarantee them for pre-existing rows, so they are kept permissive. Timestamp formats differ and this is a real inconsistency, not an oversight in this doc: publishedAt is written via new Date().toISOString() (RFC3339 with ms, e.g. “2026-07-24T10:11:12.345Z”) or null; createdAt/updatedAt default to SQLite CURRENT_TIMESTAMP and are stored as TEXT in “YYYY-MM-DD HH:MM:SS” (UTC, space separator, no timezone suffix) — NOT ISO-8601 with a T/Z.

application/json

object

definition

required

object

required

string

projectId

required

string

status

required

string

Allowed values: DRAFT PUBLISHED

templateType

required

string

Allowed values: CUSTOM B2B_SAAS CONTENT ECOMMERCE

defaultAnalysisSubject

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

analysisSubjectKey

required

Must match /^properties(.[a-zA-Z0-9_]+)+$/ when set.

string

nullable

northStarMetric

required

Free-form JSON column; not validated on write beyond “object or null”. Shape written by this app: {label: string, aggregation: “count”|“sum”, scope: GrowthAnalysisSubject, eventName: string|null, propertyPath: string|null}.

object

key

additional properties

any

aarrrStages

required

Exactly 5 stages when written through PUT (stageSchema.length(5)).

Array<object>

object

key

string

Allowed values: acquisition activation retention revenue referral

label

string

<= 40 characters

description

string

<= 200 characters

successEvents

Array<string>

<= 10 items

conversionWindowDays

integer

nullable >= 1 <= 365

defaultBreakdowns

Array<string>

<= 5 items

key

additional properties

any

defaultFunnel

required

Free-form JSON column. Shape written by this app: {scope: GrowthAnalysisSubject, windowHours: number, steps: string[]}.

object

key

additional properties

any

defaultRetention

required

Free-form JSON column. Shape written by this app: {scope: GrowthAnalysisSubject, startEvent: string|null, returnEvent: string|null, granularity: “day”|“week”|“month”}.

object

key

additional properties

any

publishedAt

required

ISO-8601 with milliseconds and Z, or null.

string

nullable

createdAt

required

SQLite CURRENT_TIMESTAMP text: ‘YYYY-MM-DD HH:MM:SS’ (UTC).

string

updatedAt

required

SQLite CURRENT_TIMESTAMP text: ‘YYYY-MM-DD HH:MM:SS’ (UTC).

string

draft

required

Server-computed suggested definition (never persisted by GET). Fully typed by createGrowthDefinitionDraft — shape is fixed.

object

status

required

string

Allowed values: DRAFT PUBLISHED

templateType

required

string

Allowed values: CUSTOM B2B_SAAS CONTENT ECOMMERCE

defaultAnalysisSubject

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

analysisSubjectKey

required

string

nullable

northStarMetric

required

object

label

required

string

aggregation

required

string

Allowed values: count sum

scope

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

eventName

required

string

nullable

propertyPath

required

string

nullable

aarrrStages

required

Array<object>

>= 5 items <= 5 items

object

key

required

string

Allowed values: acquisition activation retention revenue referral

label

required

string

description

required

string

successEvents

required

Array<string>

conversionWindowDays

required

integer

nullable

defaultBreakdowns

required

Array<string>

defaultFunnel

required

object

scope

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

windowHours

required

number

steps

required

Array<string>

defaultRetention

required

object

scope

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

startEvent

required

string

nullable

returnEvent

required

string

nullable

granularity

required

string

Allowed values: day week month

candidateEvents

required

First 12 candidate events (draft) / up to 50 (top-level events).

Array<object>

object

eventName

required

string

displayName

required

string

nullable

standardEventCode

required

string

nullable

templates

required

Static constant GROWTH_TEMPLATE_OPTIONS (4 entries).

Array<object>

object

value

required

string

Allowed values: CUSTOM B2B_SAAS CONTENT ECOMMERCE

label

required

string

description

required

string

recommendedSubject

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

subjectKeyHint

required

string

nullable

analysisSubjects

required

Static constant ANALYSIS_SUBJECT_OPTIONS (5 entries).

Array<object>

object

value

required

string

Allowed values: EVENT SESSION VISITOR IDENTIFIED_USER ACCOUNT

label

required

string

description

required

string

events

required

First 12 candidate events (draft) / up to 50 (top-level events).

Array<object>

object

eventName

required

string

displayName

required

string

nullable

standardEventCode

required

string

nullable

GET

/api/projects/{projectId}/growth-definition

1
curl --request GET \
2
  --url https://retidal.com/api/projects/%3Cstring%3E/growth-definition \
3
  --cookie trackly_session=%3CYOUR_API_KEY%3E

1
const url = 'https://retidal.com/api/projects/%3Cstring%3E/growth-definition';
2
const options = {method: 'GET', headers: {cookie: 'trackly_session=%3CYOUR_API_KEY%3E'}};
3

4
try {
5
  const response = await fetch(url, options);
6
  const data = await response.json();
7
  console.log(data);
8
} catch (error) {
9
  console.error(error);
10
}

1
import requests
2

3
url = "https://retidal.com/api/projects/%3Cstring%3E/growth-definition"
4

5
headers = {"cookie": "trackly_session=%3CYOUR_API_KEY%3E"}
6

7
response = requests.get(url, headers=headers)
8

9
print(response.json())

1
import httpx
2

3
url = "https://retidal.com/api/projects/%3Cstring%3E/growth-definition"
4

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

7
response = httpx.get(url, cookies=cookies)
8

9
print(response.json())

1
package main
2

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

9
func main() {
10

11
  url := "https://retidal.com/api/projects/%3Cstring%3E/growth-definition"
12

13
  req, _ := http.NewRequest("GET", url, nil)
14

15
  req.Header.Add("cookie", "trackly_session=%3CYOUR_API_KEY%3E")
16

17
  res, _ := http.DefaultClient.Do(req)
18

19
  defer res.Body.Close()
20
  body, _ := io.ReadAll(res.Body)
21

22
  fmt.Println(res)
23
  fmt.Println(string(body))
24

25
}

200{ definition, draft, templates, analysisSubjects, events }. Some keys are dynamic — Envelope is FIXED: {definition, draft, templates, analysisSubjects, events}. definition is null when the project has never saved one. definition ’s own columns are a fixed schema, BUT its four JSON columns (northStarMetric / aarrrStages / defaultFunnel / defaultRetention) are typed only as Record<string,unknown> / Array<Record<string,unknown>> in the repo layer and are stored as raw JSON text columns. On the WRITE path only aarrrStages is structurally validated (stageSchema, exactly 5 items) — the other three go through z.record(z.string(), z.unknown()) and are stored verbatim. The shapes the app itself writes (from createGrowthDefinitionDraft) are documented below as the observed/typical shape, but the API cannot guarantee them for pre-existing rows, so they are kept permissive. Timestamp formats differ and this is a real inconsistency, not an oversight in this doc: publishedAt is written via new Date().toISOString() (RFC3339 with ms, e.g. “2026-07-24T10:11:12.345Z”) or null; createdAt / updatedAt default to SQLite CURRENT_TIMESTAMP and are stored as TEXT in “YYYY-MM-DD HH:MM:SS” (UTC, space separator, no timezone suffix) — NOT ISO-8601 with a T/Z.

1
{
2
  "definition": {
3
    "status": "DRAFT",
4
    "templateType": "CUSTOM",
5
    "defaultAnalysisSubject": "EVENT",
6
    "aarrrStages": [
7
      {
8
        "key": "acquisition"
9
      }
10
    ]
11
  },
12
  "draft": {
13
    "status": "DRAFT",
14
    "templateType": "CUSTOM",
15
    "defaultAnalysisSubject": "EVENT",
16
    "northStarMetric": {
17
      "aggregation": "count",
18
      "scope": "EVENT"
19
    },
20
    "aarrrStages": [
21
      {
22
        "key": "acquisition"
23
      }
24
    ],
25
    "defaultFunnel": {
26
      "scope": "EVENT"
27
    },
28
    "defaultRetention": {
29
      "scope": "EVENT",
30
      "granularity": "day"
31
    }
32
  },
33
  "templates": [
34
    {
35
      "value": "CUSTOM",
36
      "recommendedSubject": "EVENT"
37
    }
38
  ],
39
  "analysisSubjects": [
40
    {
41
      "value": "EVENT"
42
    }
43
  ]
44
}