Ingest one or a batch of tracking events

Primary event-collection endpoint. Accepts a single event object, a bare array of events, or a { "events": [...] } wrapper. Batch size is capped at 100 events (over → 400).

Auth (X-API-Key header, or ?_ak=<key> / ?key=<key> query params — the query forms exist only for navigator.sendBeacon() where headers cannot be set). No explicit scope gate on this route beyond a valid project key.

Validation modes (resolved: key-level validationMode > project settings.ingestValidation.mode > warn): off = no validation; warn = validate but accept; enforce = reject schema-violating events. Only property-schema errors (not envelope warnings like a missing visitorId) cause enforce rejection.

Response mode:

default → 202 { accepted, failed, queued, processed:false, invalid? } — events validated and dispatched into ctx.waitUntil; persistence is async and NOT proven. Do not treat 202 as durable persistence.
?sync=1 or X-Trackly-Sync: 1 → 200 { accepted, failed, queued, processed:true, errors?, enforceRejected? } — non-metering events reached D1 + Analytics Engine before the response. For debugging/health checks only.
enforce mode + all events rejected (sync path) → 422.

Metering (conversion) events are enqueued synchronously to the metering ingest queue before any response; a missing queue binding or a send failure yields 503. ?debug=1 (or a per-event _debug flag) captures samples into DebugView.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

sync

string

Allowed values: 1

1 forces synchronous processing (200 with processed:true). Equivalent to the X-Trackly-Sync: 1 header.

debug

string

When truthy, invalid/accepted event samples are captured into DebugView for the project (best-effort; never affects ingest outcome).

_ak

string

API key fallback (sendBeacon). Prefer the X-API-Key header.

key

string

API key fallback (lowest precedence). Prefer the X-API-Key header.

Header Parameters

X-Trackly-Sync

string

Allowed values: 1

1 forces synchronous processing (same effect as ?sync=1).

Request Body^required

A single event object, a bare array of events, or a { "events": [...] } wrapper. Max 100 events per request.

application/json

One of:

A single tracking event. eventName is required; everything else is optional. Every field accepts both camelCase and snake_case aliases (e.g. visitorId/visitor_id). Unknown top-level keys are preserved as part of the raw envelope, except the internal derived-event provenance fields (source, derivedRuleId, derivationDepth) which are hard-stripped from external payloads.

object

eventName

required

Event name (aliases event / event_name). Envelope validation expects ^[a-z0-9_]{1,100}$; a non-matching name is a warn-level error (still processed). A missing eventName marks the event invalid.

string

visitorId

Device/browser-level ID (alias visitor_id). Defaults to "anon" if omitted (warn-level).

string

userId

Logged-in user ID (alias user_id).

string

sessionId

Session ID (alias session_id). Tier-1 attribution key.

string

properties

Custom key-value payload. Monetary amounts go in amount (or value) in minor units (cents). currency defaults to CNY. Max ~32 KB serialized (warn-level properties_too_large over the limit).

object

key

additional properties

any

clientTimestamp

Event time, ISO 8601 (aliases client_timestamp / timestamp). Unparseable values are a warn-level error.

string

eventId

Optional client-supplied idempotency/dedup key (alias event_id). Must match ^[A-Za-z0-9_.-]{8,64}$; otherwise it is ignored (with a warning) and the server generates one. REQUIRED for metering events on the backfill endpoint.

string

shortLinkId

Short-link ID for explicit attribution (alias short_link_id).

string

shortLinkCode

Short code for direct-landing attribution (aliases _tk / short_link_code).

string

clickIds

Recommended unified Click ID map covering all 29 ad platforms, e.g. { "bd_vid": "...", "gclid": "..." }. Alternatives: a top-level click_id, or legacy strongly-typed top-level fields (bdVid, gclid, fbclid, … — cover only the earlier ~15 platforms).

object

key

additional properties

string

url

Full page URL; Click IDs are auto-extracted from its query string.

string

landingUrl

string

referrer

string

utmSource

Alias utm_source

string

utmMedium

Alias utm_medium

string

utmCampaign

Alias utm_campaign

string

utmTerm

Alias utm_term

string

utmContent

Alias utm_content

string

Array<object>

<= 100 items

object

eventName

required

string

visitorId

Device/browser-level ID (alias visitor_id). Defaults to "anon" if omitted (warn-level).

string

userId

Logged-in user ID (alias user_id).

string

sessionId

Session ID (alias session_id). Tier-1 attribution key.

string

properties

object

key

additional properties

any

clientTimestamp

Event time, ISO 8601 (aliases client_timestamp / timestamp). Unparseable values are a warn-level error.

string

eventId

string

shortLinkId

Short-link ID for explicit attribution (alias short_link_id).

string

shortLinkCode

Short code for direct-landing attribution (aliases _tk / short_link_code).

string

clickIds

object

key

additional properties

string

url

Full page URL; Click IDs are auto-extracted from its query string.

string

landingUrl

string

referrer

string

utmSource

Alias utm_source

string

utmMedium

Alias utm_medium

string

utmCampaign

Alias utm_campaign

string

utmTerm

Alias utm_term

string

utmContent

Alias utm_content

string

object

events

required

Array<object>

<= 100 items

object

eventName

required

string

visitorId

Device/browser-level ID (alias visitor_id). Defaults to "anon" if omitted (warn-level).

string

userId

Logged-in user ID (alias user_id).

string

sessionId

Session ID (alias session_id). Tier-1 attribution key.

string

properties

object

key

additional properties

any

clientTimestamp

Event time, ISO 8601 (aliases client_timestamp / timestamp). Unparseable values are a warn-level error.

string

eventId

string

shortLinkId

Short-link ID for explicit attribution (alias short_link_id).

string

shortLinkCode

Short code for direct-landing attribution (aliases _tk / short_link_code).

string

clickIds

object

key

additional properties

string

url

Full page URL; Click IDs are auto-extracted from its query string.

string

landingUrl

string

referrer

string

utmSource

Alias utm_source

string

utmMedium

Alias utm_medium

string

utmCampaign

Alias utm_campaign

string

utmTerm

Alias utm_term

string

utmContent

Alias utm_content

string

Examples

Single purchase event

1
{
2
  "eventName": "user_paid",
3
  "visitorId": "vid_abc123",
4
  "userId": "uid_456",
5
  "sessionId": "sess_789",
6
  "properties": {
7
    "amount": 9900,
8
    "currency": "CNY"
9
  },
10
  "clickIds": {
11
    "bd_vid": "abc",
12
    "gclid": "xyz"
13
  }
14
}

Wrapped batch

1
{
2
  "events": [
3
    {
4
      "eventName": "page_view",
5
      "visitorId": "vid_abc123"
6
    },
7
    {
8
      "eventName": "user_paid",
9
      "visitorId": "vid_abc123",
10
      "properties": {
11
        "amount": 4900
12
      }
13
    }
14
  ]
15
}

Responses

200

Synchronous result (?sync=1). processed:true proves non-metering events reached D1 + Analytics Engine.

application/json

Synchronous (?sync=1) ingest response — also the 422 body in enforce mode.

object

accepted

required

Events written to D1 + Analytics Engine (= total minus enforce-rejected).

integer

failed

required

Invalid events plus enforce-rejected events.

integer

queued

required

Metering events enqueued.

integer

processed

required

Always true on the sync path.

boolean

errors

Per-event validation errors (present only when non-empty).

Array<object>

Validation errors for a single event (sync=1 / 422 response).

object

index

0-based batch index.

integer

eventName

string

errors

Array<object>

Structured validation error (envelope or property-schema).

object

field

required

string

rule

required

Rule identifier, e.g. type, required, enum, pattern, minimum, maximum, maxLength, or envelope rules like envelope/event_name_format, envelope/visitor_id_missing.

string

expected

Expected value/constraint (any type).

actual

Actual value/type observed (any type).

message

required

string

enforceRejected

Number of events rejected by enforce-mode schema validation (present only when > 0).

integer

202

Accepted (default async). Events dispatched to background processing; persistence completes after the response and is not guaranteed.

application/json

Default 202 async ingest response.

object

accepted

required

Events validated and dispatched to background processing (NOT proof of persistence).

integer

failed

required

Count of invalid (unparseable / missing eventName) events.

integer

queued

required

Metering events enqueued to the metering ingest queue.

integer

processed

required

Always false on the async path.

boolean

invalid

Present only when there are invalid events.

Array<object>

An event rejected at the envelope/parse layer.

object

index

required

0-based position in the incoming batch.

integer

rawSample

required

Raw event sample truncated to ≤1KB.

string

reason

required

Human-readable rejection reason (e.g. “缺少 eventName 字段”).

string

Example

1
{
2
  "accepted": 2,
3
  "failed": 0,
4
  "queued": 2,
5
  "processed": false
6
}

400

Invalid JSON body, or batch exceeds 100 events.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "无效的 JSON 格式"
3
}

1
{
2
  "error": "单次最多提交 100 个事件"
3
}

401

Missing or invalid API key.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "缺少 X-API-Key 请求头"
3
}

1
{
2
  "error": "API Key 无效"
3
}

422

Enforce mode and every event was rejected (sync path only).

application/json

Synchronous (?sync=1) ingest response — also the 422 body in enforce mode.

object

accepted

required

Events written to D1 + Analytics Engine (= total minus enforce-rejected).

integer

failed

required

Invalid events plus enforce-rejected events.

integer

queued

required

Metering events enqueued.

integer

processed

required

Always true on the sync path.

boolean

errors

Per-event validation errors (present only when non-empty).

Array<object>

Validation errors for a single event (sync=1 / 422 response).

object

index

0-based batch index.

integer

eventName

string

errors

Array<object>

Structured validation error (envelope or property-schema).

object

field

required

string

rule

required

Rule identifier, e.g. type, required, enum, pattern, minimum, maximum, maxLength, or envelope rules like envelope/event_name_format, envelope/visitor_id_missing.

string

expected

Expected value/constraint (any type).

actual

Actual value/type observed (any type).

message

required

string

enforceRejected

Number of events rejected by enforce-mode schema validation (present only when > 0).

integer

Example

1
{
2
  "accepted": 0,
3
  "failed": 1,
4
  "queued": 0,
5
  "processed": true,
6
  "enforceRejected": 1,
7
  "errors": [
8
    {
9
      "index": 0,
10
      "eventName": "user_paid",
11
      "errors": [
12
        {
13
          "field": "amount",
14
          "rule": "type",
15
          "expected": "number",
16
          "actual": "string",
17
          "message": "Field amount: expected number, got string"
18
        }
19
      ]
20
    }
21
  ]
22
}

503

Transient infra failure. SELECTOR_LOOKUP_FAILED (retryAfter 30) when the metering-selector lookup fails; QUEUE_UNAVAILABLE (retryAfter 60) when metering events are present but the queue binding is absent or the enqueue send failed.

application/json

503 transient error with a suggested retry delay.

object

error

required

string

Allowed values: SELECTOR_LOOKUP_FAILED QUEUE_UNAVAILABLE

retryAfter

required

Suggested seconds to wait before retrying (30 or 60).

integer

Examples

1
{
2
  "error": "SELECTOR_LOOKUP_FAILED",
3
  "retryAfter": 30
4
}

1
{
2
  "error": "QUEUE_UNAVAILABLE",
3
  "retryAfter": 60
4
}

POST

/api/v1/t

1
curl --request POST \
2
  --url https://api.retidal.com/api/v1/t \
3
  --header 'Content-Type: application/json' \
4
  --header 'X-API-Key: <YOUR_API_KEY>' \
5
  --data '{
6
  "eventName": "user_paid",
7
  "visitorId": "vid_abc123",
8
  "userId": "uid_456",
9
  "sessionId": "sess_789",
10
  "properties": {
11
    "amount": 9900,
12
    "currency": "CNY"
13
  },
14
  "clickIds": {
15
    "bd_vid": "abc",
16
    "gclid": "xyz"
17
  }
18
}'

1
const url = 'https://api.retidal.com/api/v1/t';
2
const options = {
3
  method: 'POST',
4
  headers: {'X-API-Key': '<YOUR_API_KEY>', 'Content-Type': 'application/json'},
5
  body: '{"eventName":"user_paid","visitorId":"vid_abc123","userId":"uid_456","sessionId":"sess_789","properties":{"amount":9900,"currency":"CNY"},"clickIds":{"bd_vid":"abc","gclid":"xyz"}}'
6
};
7

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

1
import requests
2

3
url = "https://api.retidal.com/api/v1/t"
4

5
payload = {
6
    "eventName": "user_paid",
7
    "visitorId": "vid_abc123",
8
    "userId": "uid_456",
9
    "sessionId": "sess_789",
10
    "properties": {
11
        "amount": 9900,
12
        "currency": "CNY"
13
    },
14
    "clickIds": {
15
        "bd_vid": "abc",
16
        "gclid": "xyz"
17
    }
18
}
19
headers = {
20
    "X-API-Key": "<YOUR_API_KEY>",
21
    "Content-Type": "application/json"
22
}
23

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

26
print(response.json())

1
import httpx
2
import json
3

4
url = "https://api.retidal.com/api/v1/t"
5

6
headers = {"X-API-Key": "<YOUR_API_KEY>"}
7

8
payload = json.loads("{\n  \"eventName\": \"user_paid\",\n  \"visitorId\": \"vid_abc123\",\n  \"userId\": \"uid_456\",\n  \"sessionId\": \"sess_789\",\n  \"properties\": {\n    \"amount\": 9900,\n    \"currency\": \"CNY\"\n  },\n  \"clickIds\": {\n    \"bd_vid\": \"abc\",\n    \"gclid\": \"xyz\"\n  }\n}")
9

10
response = httpx.post(url, headers=headers, 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://api.retidal.com/api/v1/t"
13

14
  payload := strings.NewReader("{\n  \"eventName\": \"user_paid\",\n  \"visitorId\": \"vid_abc123\",\n  \"userId\": \"uid_456\",\n  \"sessionId\": \"sess_789\",\n  \"properties\": {\n    \"amount\": 9900,\n    \"currency\": \"CNY\"\n  },\n  \"clickIds\": {\n    \"bd_vid\": \"abc\",\n    \"gclid\": \"xyz\"\n  }\n}")
15

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

18
  req.Header.Add("X-API-Key", "<YOUR_API_KEY>")
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
}

200Synchronous result ( ?sync=1 ). processed:true proves non-metering events reached D1 + Analytics Engine.

1
{
2
  "accepted": 1,
3
  "failed": 0,
4
  "queued": 0,
5
  "processed": true
6
}

Ingest one or a batch of tracking events

Authorizations

Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Examples

Responses

200

202

Example

400

Examples

401

Examples

422

Example

503

Examples

Request Body^required