Backfill historical events (synchronous, up to 1000)

Bulk-loads historical events. Same batch shapes as /api/v1/t but the cap is 1000 (over → 400). Processing is synchronous and always returns processed:true.

Metering (conversion) events MUST carry a client-provided eventId (format ^[A-Za-z0-9_.-]{8,64}$) so the ledger can deduplicate; any missing one fails the whole request with 400 MISSING_EVENT_ID and the 0-based affectedIndices.

Auth: X-API-Key (also ?_ak / ?key), no extra scope gate.

Authorizations

ApiKeyAuth

Request Body^required

Single event, array, or { "events": [...] } wrapper (max 1000).

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>

<= 1000 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>

<= 1000 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

Example

1
{
2
  "events": [
3
    {
4
      "eventName": "user_paid",
5
      "visitorId": "vid_abc123",
6
      "eventId": "order-2026-0001",
7
      "properties": {
8
        "amount": 9900,
9
        "currency": "CNY"
10
      },
11
      "clientTimestamp": "2026-06-01T08:00:00Z"
12
    }
13
  ]
14
}

Responses

200

Backfill processed.

application/json

object

accepted

required

integer

failed

required

integer

processed

required

boolean

mode

required

string

Allowed value: backfill

400

Invalid JSON, batch over 1000, or metering events missing eventId.

application/json

One of:

object
object

object

error

required

Human-readable error message.

string

retryAfter

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

integer

message

string

affectedIndices

Array<integer>

400 returned when metering events in a backfill batch lack eventId.

object

error

required

string

Allowed value: MISSING_EVENT_ID

affectedIndices

required

0-based indices of the offending events.

Array<integer>

message

required

string

Examples

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

1
{
2
  "error": "MISSING_EVENT_ID",
3
  "affectedIndices": [
4
    0,
5
    3
6
  ],
7
  "message": "计量级事件 backfill 必须提供 eventId"
8
}

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>

Example^generated

1
{
2
  "error": "example",
3
  "retryAfter": 1,
4
  "message": "example",
5
  "affectedIndices": [
6
    1
7
  ]
8
}

503

Metering-selector lookup failed (fail-closed). Retry after 30s.

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

Example

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

POST

/internal/backfill/events

1
curl --request POST \
2
  --url https://api.retidal.com/internal/backfill/events \
3
  --header 'Content-Type: application/json' \
4
  --header 'X-API-Key: <YOUR_API_KEY>' \
5
  --data '{
6
  "events": [
7
    {
8
      "eventName": "user_paid",
9
      "visitorId": "vid_abc123",
10
      "eventId": "order-2026-0001",
11
      "properties": {
12
        "amount": 9900,
13
        "currency": "CNY"
14
      },
15
      "clientTimestamp": "2026-06-01T08:00:00Z"
16
    }
17
  ]
18
}'

1
const url = 'https://api.retidal.com/internal/backfill/events';
2
const options = {
3
  method: 'POST',
4
  headers: {'X-API-Key': '<YOUR_API_KEY>', 'Content-Type': 'application/json'},
5
  body: '{"events":[{"eventName":"user_paid","visitorId":"vid_abc123","eventId":"order-2026-0001","properties":{"amount":9900,"currency":"CNY"},"clientTimestamp":"2026-06-01T08:00:00Z"}]}'
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/internal/backfill/events"
4

5
payload = { "events": [
6
        {
7
            "eventName": "user_paid",
8
            "visitorId": "vid_abc123",
9
            "eventId": "order-2026-0001",
10
            "properties": {
11
                "amount": 9900,
12
                "currency": "CNY"
13
            },
14
            "clientTimestamp": "2026-06-01T08:00:00Z"
15
        }
16
    ] }
17
headers = {
18
    "X-API-Key": "<YOUR_API_KEY>",
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://api.retidal.com/internal/backfill/events"
5

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

8
payload = json.loads("{\n  \"events\": [\n    {\n      \"eventName\": \"user_paid\",\n      \"visitorId\": \"vid_abc123\",\n      \"eventId\": \"order-2026-0001\",\n      \"properties\": {\n        \"amount\": 9900,\n        \"currency\": \"CNY\"\n      },\n      \"clientTimestamp\": \"2026-06-01T08:00:00Z\"\n    }\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/internal/backfill/events"
13

14
  payload := strings.NewReader("{\n  \"events\": [\n    {\n      \"eventName\": \"user_paid\",\n      \"visitorId\": \"vid_abc123\",\n      \"eventId\": \"order-2026-0001\",\n      \"properties\": {\n        \"amount\": 9900,\n        \"currency\": \"CNY\"\n      },\n      \"clientTimestamp\": \"2026-06-01T08:00:00Z\"\n    }\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
}

200Backfill processed.

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

Backfill historical events (synchronous, up to 1000)

Authorizations

Request Bodyrequired

Example

Responses

200

400

Examples

401

Examplegenerated

503

Example

Request Body^required

Example^generated