SCscrunch
ai-referrals

Push AI Referrals Events

Changed on

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

Request

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

The landing page, as a path (e.g. '/pricing') or a full URL. Stored as sent; read by its path, without the query.

pageviewsinteger nullable
sessionsinteger nullable
transactionsinteger nullable
purchase_revenuenumber nullable
currency_codestring nullable

ISO 4217 code of purchase_revenue (e.g. USD). Required when purchase_revenue isn't 0. A connection keeps one currency.

usersinteger nullable

Users who arrived from the AI platform that day. Send all six engagement fields or none.

new_usersinteger nullable

Of those, users new to the website.

engaged_sessionsinteger nullable

Sessions with engagement, by your tool's definition.

engagement_secondsnumber nullable

Total engagement time of the row's sessions, in seconds.

key_eventsinteger nullable

Conversion events in the row's sessions.

converted_sessionsinteger nullable

Sessions with at least one conversion.

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.

Changes

  • 3c6aa69a6595Revision changes
    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status