> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml /api-reference/openapi.json post /{brand_id}/ai-referrals/connections/{connection_id}/events
openapi: 3.1.0
info:
  title: Scrunch Data API
  version: 0.1.0
servers:
  - url: https://api.scrunchai.com/v1
security: []
paths:
  /{brand_id}/ai-referrals/connections/{connection_id}/events:
    post:
      tags:
        - ai-referrals
      summary: Push AI Referrals Events
      description: >-
        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.
      operationId: pushAiReferralsEvents
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: integer
            title: Brand Id
          description: The unique identifier for the brand.
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            title: Connection Id
          description: The ULID of the AI Referrals connection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AiReferralsEvent'
          application/x-ndjson:
            schema:
              type: string
              description: Newline-delimited JSON, one event object per line.
      responses:
        '200':
          description: Batch accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiReferralsSaveResult'
        '400':
          description: Malformed payload (invalid JSON, empty body, unexpected shape).
        '404':
          description: Connection not found for this brand.
        '410':
          description: Connection is disabled; re-register before retrying.
        '413':
          description: Payload too large (over 10,000 events or 5 MB).
        '422':
          description: One or more events failed validation.
      security:
        - HTTPBearer:
            - configure
components:
  schemas:
    AiReferralsEvent:
      type: object
      description: One pre-aggregated daily referral row.
      required:
        - date
        - raw_referrer_value
        - raw_page_value
      properties:
        date:
          type: string
          format: date
          description: UTC calendar day the metrics cover.
          example: '2026-05-20'
        raw_referrer_value:
          type: string
          minLength: 1
          maxLength: 512
          description: >-
            Raw referrer value as emitted by the source analytics tool (e.g.
            'chatgpt.com'). Normalized server-side against the AI platform
            allow-list.
          example: chatgpt.com
        raw_page_value:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            Raw page identifier from the source tool (URL path for GA4-shape
            tools; page name for Adobe unless a URL eVar is configured).
          example: /blog/launch-notes
        pageviews:
          type:
            - integer
            - 'null'
          minimum: 0
        sessions:
          type:
            - integer
            - 'null'
          minimum: 0
        transactions:
          type:
            - integer
            - 'null'
          minimum: 0
        purchase_revenue:
          type:
            - number
            - 'null'
          minimum: 0
        batch_id:
          type:
            - string
            - 'null'
          maxLength: 128
          description: Optional client-supplied batch identifier for traceability.
    AiReferralsSaveResult:
      type: object
      description: Outcome of a push batch submission.
      required:
        - accepted
        - rejected
      properties:
        accepted:
          type: integer
          description: Number of events accepted into the unified referrals store.
        rejected:
          type: integer
          description: >-
            Number of events dropped (e.g. referrer not on the AI platform
            allow-list).
        errors:
          type: array
          items:
            type: string
          description: Per-row diagnostic messages, truncated.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````