---
title: "Push AI Referrals Events"
method: POST
path: "/{brand_id}/ai-referrals/connections/{connection_id}/events"
tags: ["ai-referrals"]
---

# Push AI Referrals Events

`POST /{brand_id}/ai-referrals/connections/{connection_id}/events`

## Request

- Base URL: `https://api.scrunchai.com/v1`
- URL: `https://api.scrunchai.com/v1/{brand_id}/ai-referrals/connections/{connection_id}/events`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/scrunch/apis/scrunch-data-api/docs/:brand_id/ai-referrals/connections/:connection_id/events/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `brand_id` integer, required
- `connection_id` string, required

## Request body

- AiReferralsEvent[]
  - `date` string, date, required: UTC calendar day the metrics cover.
  - `raw_referrer_value` string, 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_value` string, required: The landing page, as a path (e.g. '/pricing') or a full URL. Stored as sent; read by its path, without the query.
  - `pageviews` integer, nullable
  - `sessions` integer, nullable
  - `transactions` integer, nullable
  - `purchase_revenue` number, nullable
  - `currency_code` string, nullable: ISO 4217 code of purchase_revenue (e.g. USD). Required when purchase_revenue isn't 0. A connection keeps one currency.
  - `users` integer, nullable: Users who arrived from the AI platform that day. Send all six engagement fields or none.
  - `new_users` integer, nullable: Of those, users new to the website.
  - `engaged_sessions` integer, nullable: Sessions with engagement, by your tool's definition.
  - `engagement_seconds` number, nullable: Total engagement time of the row's sessions, in seconds.
  - `key_events` integer, nullable: Conversion events in the row's sessions.
  - `converted_sessions` integer, nullable: Sessions with at least one conversion.
  - `batch_id` string, nullable: Optional client-supplied batch identifier for traceability.

## Response `200`

Batch accepted.

- AiReferralsSaveResult: Outcome of a push batch submission.
  - `accepted` integer, required: Number of events accepted into the unified referrals store.
  - `rejected` integer, required: Number of events dropped (e.g. referrer not on the AI platform allow-list).
  - `errors` string[]: Per-row diagnostic messages, truncated.

## Other responses

- `400`: Malformed payload (invalid JSON, empty body, unexpected shape), a batch mixing rows with and without users, engagement and key events, or a batch mixing revenue currencies.
- `404`: Connection not found for this brand, or the AI Referrals API isn't enabled for it.
- `409`: The batch doesn't match what the connection already sends: users, engagement and key events or traffic only, and its revenue currency. Register the website again to change either.
- `410`: Connection is disabled; re-register before retrying.
- `413`: Payload too large (over 10,000 events or 5 MB).
- `422`: One or more events failed validation.
- `429`: More than 120 calls a minute for the brand. Nothing is stored; retry after the seconds in the Retry-After header.

## Changes

- **2026-11-05** `3c6aa69a6595`: 9 info
  - added the new optional request property `items/converted_sessions`
  - added the new optional request property `items/currency_code`
  - added the new optional request property `items/engaged_sessions`
  - added the new optional request property `items/engagement_seconds`
  - …5 more

[Operation history](https://skmtc.dev/scrunch/apis/scrunch-data-api/changes/:brand_id/ai-referrals/connections/:connection_id/events/post.md)

---

[API](https://skmtc.dev/scrunch/apis/scrunch-data-api.md) - [All operations](https://skmtc.dev/scrunch/apis/scrunch-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scrunch/apis/scrunch-data-api/revisions/e28a10a186bf?raw)