Paginated visit/session feed

Authorizations

SessionCookie

Parameters

Path Parameters

projectId

required

string

Query Parameters

page

integer

default: 1 >= 1

pageSize

integer

default: 20 >= 1 <= 100

startDate

string format: date

Inclusive window start (YYYY-MM-DD). Parsed with parseDateRangeParams; when either startDate or endDate is missing/invalid the route falls back to a rolling default window (30 days for events/visits/attribution, 7 days for growth).

endDate

string format: date

Inclusive window end (YYYY-MM-DD). See startDate for fallback behavior.

search

string

Responses

200

Paginated visit feed. Two code paths produce the SAME field set. Primary path reads D1 visit_attributions. If that returns total === 0, the service falls back to Analytics Engine visit rows; in that fallback id is the synthetic “ae:::<sessionId|‘’>”, ip/userAgent/shortLink are always null, deviceType defaults to “UNKNOWN”, clickIds is at most a single-entry map, and createdAt is the ClickHouse datetime string “YYYY-MM-DD HH:MM:SS”. On the D1 path createdAt is normalizeUtcTimestamp(…) of the stored value (ISO-8601 UTC) with the raw stored string as fallback, and userAgent is hardcoded null in both paths. clickIds keys are ad-platform click-ID parameter names (gclid, fbclid, bd_vid, …) — an open-ended map of string→string.

application/json

object

visits

required

Array<object>

object

required

string

sessionId

required

Empty string when unknown

string

visitorId

required

Empty string when unknown (D1 path)

string

userId

required

string | null

landingUrl

required

Empty string when unknown

string

referrer

required

string | null

utmSource

required

string | null

utmMedium

required

string | null

utmCampaign

required

string | null

country

required

string | null

deviceType

required

string

clickIds

required

Map of ad-platform click-ID parameter name → value; keys are open-ended.

object | null

required

string | null

userAgent

required

Always null (not persisted / not selected)

null

createdAt

required

D1 path: ISO-8601 UTC (normalized), raw stored string as fallback. AE fallback path: “YYYY-MM-DD HH:MM:SS”.

string

shortLink

required

Always null on the AE fallback path.

object

required

string

name

required

string | null

shortCode

required

string

campaign

required

object

required

string

name

required

string

adPlatformConfig

required

object

required

string

name

required

string

platform

required

string

total

required

Total matching visits (D1 COUNT, or filtered AE row count on the fallback path).

integer

GET

/api/projects/{projectId}/visits

1
curl --request GET \
2
  --url 'https://retidal.com/api/projects/%3Cstring%3E/visits?page=1&pageSize=20' \
3
  --cookie trackly_session=%3CYOUR_API_KEY%3E

1
const url = 'https://retidal.com/api/projects/%3Cstring%3E/visits?page=1&pageSize=20';
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/visits"
4

5
querystring = {"page":"1","pageSize":"20"}
6

7
headers = {"cookie": "trackly_session=%3CYOUR_API_KEY%3E"}
8

9
response = requests.get(url, headers=headers, params=querystring)
10

11
print(response.json())

1
import httpx
2

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

5
params = [("page", "1"), ("pageSize", "20")]
6

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

9
response = httpx.get(url, params=params, cookies=cookies)
10

11
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/visits?page=1&pageSize=20"
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
}

200Paginated visit feed. Two code paths produce the SAME field set. Primary path reads D1 visit_attributions. If that returns total === 0, the service falls back to Analytics Engine visit rows; in that fallback id is the synthetic “ae: : :<sessionId|‘’>”, ip / userAgent / shortLink are always null, deviceType defaults to “UNKNOWN”, clickIds is at most a single-entry map, and createdAt is the ClickHouse datetime string “YYYY-MM-DD HH:MM:SS”. On the D1 path createdAt is normalizeUtcTimestamp(…) of the stored value (ISO-8601 UTC) with the raw stored string as fallback, and userAgent is hardcoded null in both paths. clickIds keys are ad-platform click-ID parameter names (gclid, fbclid, bd_vid, …) — an open-ended map of string→string.

1
{
2
  "visits": [
3
    {
4
      "id": "example",
5
      "sessionId": "example",
6
      "visitorId": "example",
7
      "userId": "example",
8
      "landingUrl": "example",
9
      "referrer": "example",
10
      "utmSource": "example",
11
      "utmMedium": "example",
12
      "utmCampaign": "example",
13
      "country": "example",
14
      "deviceType": "example",
15
      "clickIds": "example",
16
      "ip": "example",
17
      "userAgent": "example",
18
      "createdAt": "example",
19
      "shortLink": {
20
        "id": "example",
21
        "name": "example",
22
        "shortCode": "example",
23
        "campaign": {
24
          "id": "example",
25
          "name": "example"
26
        },
27
        "adPlatformConfig": {
28
          "id": "example",
29
          "name": "example",
30
          "platform": "example"
31
        }
32
      }
33
    }
34
  ],
35
  "total": 1
36
}