v1

latestOpenAPI 3.1.02026-07-263370112.1 KB

ai-referrals

Push AI Referrals Events

Push a batch of pre-aggregated daily AI-referral events for a registered connection.

Accepts application/json (a JSON array of events) or application/x-ndjson (one event per line). The upsert key is (date, raw_referrer_value, raw_page_value) — re-sending the same tuple replaces the prior values, so backfills and corrections are safe to retry.

Limits:

Maximum 10,000 events per batch.
Maximum 5 MB request body.

post/{brand_id}/ai-referrals/connections/{connection_id}/events

Path parameters

brand_idinteger required

The unique identifier for the brand.

connection_idstring required

The ULID of the AI Referrals connection.

Request body

datestring date required

UTC calendar day the metrics cover.

raw_referrer_valuestring required

Raw referrer value as emitted by the source analytics tool (e.g. 'chatgpt.com'). Normalized server-side against the AI platform allow-list.

raw_page_valuestring required

Raw page identifier from the source tool (URL path for GA4-shape tools; page name for Adobe unless a URL eVar is configured).

pageviewsinteger nullable

sessionsinteger nullable

transactionsinteger nullable

purchase_revenuenumber nullable

batch_idstring nullable

Optional client-supplied batch identifier for traceability.

Example request

[
  {
    "date": "2026-05-20",
    "raw_referrer_value": "chatgpt.com",
    "raw_page_value": "/blog/launch-notes"
  }
]

Response

Batch accepted.

acceptedinteger required

Number of events accepted into the unified referrals store.

rejectedinteger required

Number of events dropped (e.g. referrer not on the AI platform allow-list).

errorsstring[]

Per-row diagnostic messages, truncated.