AI Referrals API: Push AI-Sourced Traffic Data

Overview

The AI Referrals API ingests pre-aggregated daily traffic that originated from AI assistants (ChatGPT, Claude, Perplexity, and so on) into Scrunch. Use it when your source of truth for web analytics is Adobe Analytics or another tool you’d like to push from on a schedule, rather than connecting Google Analytics directly. Once a connection is registered and events start landing, the AI Traffic dashboard and the Site Map’s ai_referrals metric prefer push data over any live-queried Google Analytics integration for the same website.

When to use the AI Referrals API

Use this API when you need to:

Send AI-sourced traffic from Adobe Analytics into Scrunch on a daily schedule.
Backfill historical AI referral data from any pre-aggregated source.
Power the AI Traffic dashboard for brands that don’t use Google Analytics.

If your team uses Google Analytics 4, connect it through the in-app integration instead — you don’t need this API. A brand cannot have both a Google Analytics integration and an active AI Referrals push connection on the same website at the same time.

How it works

Register a connection for the (brand, website, provider) you’ll push from. Connections are scoped to one website each; register multiple connections if you push for several domains.
Push events in batches against that connection. Each event is one row of pre-aggregated daily metrics — pageviews, sessions, transactions, and revenue — keyed by date, referrer, and page.
Read results on the AI Traffic dashboard and via the Sitemap API’s ai_referrals totals.

Pushes are idempotent. The upsert key is (date, raw_referrer_value, raw_page_value) — resending the same tuple replaces the prior values, so retries and corrections are safe.

Authentication

All endpoints use Bearer-token authentication. Connection writes require the configure scope; listing requires the query scope.

export SCRUNCH_API_TOKEN="your-key"

Generate a key under Organization → Settings → API Keys in the Scrunch dashboard.

Endpoints

Method	Path	Purpose
`POST`	`/{brand_id}/ai-referrals/connections`	Register a push connection for one website and provider.
`GET`	`/{brand_id}/ai-referrals/connections`	List the brand’s push connections.
`DELETE`	`/{brand_id}/ai-referrals/connections/{connection_id}`	Soft-disable a connection.
`POST`	`/{brand_id}/ai-referrals/connections/{connection_id}/events`	Push a batch of pre-aggregated daily events.

The list endpoint returns push connections only. Google Analytics integrations live in a separate system and don’t appear here, even when they’re the reason a register call returned 409.

Supported providers

The MVP allow-list is:

adobe_analytics

More providers will be added behind the same provider field — your code doesn’t need to change when the allow-list grows.

Event schema

Each event is one pre-aggregated daily row.

Field	Type	Required	Description
`date`	string (`YYYY-MM-DD`)	Yes	UTC calendar day the metrics cover.
`raw_referrer_value`	string	Yes	Raw referrer from the source tool (e.g. `chatgpt.com`). Normalized server-side against the AI platform allow-list.
`raw_page_value`	string	Yes	Raw page identifier — URL path for GA-shape tools, page name for Adobe unless a URL eVar is configured.
`pageviews`	integer	No	Pageviews for the row. Must be ≥ 0.
`sessions`	integer	No	Sessions for the row. Must be ≥ 0.
`transactions`	integer	No	Completed transactions, when available.
`purchase_revenue`	number	No	Revenue attributed to the row.
`batch_id`	string	No	Optional client-supplied identifier for traceability.

Example: register a connection

curl -X POST "https://api.scrunchai.com/v1/1234/ai-referrals/connections" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "example.com",
    "provider": "adobe_analytics"
  }'

Response:

{
  "id": "01JX2Y6E8H1AKQ8V0W7G4D9SXT",
  "brand_id": 1234,
  "website": "example.com",
  "provider": "adobe_analytics",
  "status": "active",
  "created_at": "2026-05-24T12:00:00Z",
  "last_pushed_at": null,
  "last_push_error": null
}

Save the returned id — you’ll use it as connection_id on every push.

Example: push a batch (JSON array)

curl -X POST \
  "https://api.scrunchai.com/v1/1234/ai-referrals/connections/01JX2Y6E8H1AKQ8V0W7G4D9SXT/events" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "date": "2026-05-20",
      "raw_referrer_value": "chatgpt.com",
      "raw_page_value": "/blog/launch-notes",
      "pageviews": 412,
      "sessions": 298,
      "transactions": 7,
      "purchase_revenue": 1842.50
    },
    {
      "date": "2026-05-20",
      "raw_referrer_value": "perplexity.ai",
      "raw_page_value": "/pricing",
      "pageviews": 88,
      "sessions": 71
    }
  ]'

Response:

{
  "accepted": 2,
  "rejected": 0,
  "errors": []
}

Events whose raw_referrer_value doesn’t match Scrunch’s AI platform allow-list are counted in rejected rather than failing the whole batch.

Example: push a batch (NDJSON)

For larger batches, send newline-delimited JSON to reduce parser overhead:

curl -X POST \
  "https://api.scrunchai.com/v1/1234/ai-referrals/connections/01JX2Y6E8H1AKQ8V0W7G4D9SXT/events" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary $'{"date":"2026-05-20","raw_referrer_value":"chatgpt.com","raw_page_value":"/blog/a","pageviews":12}\n{"date":"2026-05-20","raw_referrer_value":"claude.ai","raw_page_value":"/blog/b","pageviews":3}'

Limits

10,000 events per batch. Larger batches return 413 Payload Too Large — split and retry.
5 MB request body. Same 413 behavior.
One active connection per (brand_id, website). Disable the existing connection or use a different website before re-registering.

Status codes

Status	Meaning
`200`	Batch accepted. The response body reports `accepted` and `rejected` counts.
`201`	Connection registered.
`400`	Malformed payload, invalid provider, or empty body.
`404`	Brand or connection not found.
`409`	A connection or conflicting integration already exists for this `(brand, website)`.
`410`	Connection is disabled — re-register before pushing again.
`413`	Batch exceeds the 10,000-event or 5 MB cap.
`422`	One or more events failed schema validation. The body includes per-row errors.

Best practices

Push once per day after your source tool has finalized the prior day’s data. The upsert key makes re-pushes safe, but daily granularity is enough for the dashboard.
Send raw referrer values straight from your source tool — don’t pre-normalize. Scrunch maps them to AI platforms server-side and that mapping evolves over time.
Include batch_id when you can. It makes it easier to correlate a push with your ETL run if you need to investigate later.
Back off on 429/5xx with exponential retry. Pushes are idempotent on the upsert key.
Don’t mix providers on one connection. Register one connection per (website, provider).

​Overview

​When to use the AI Referrals API

​How it works

​Authentication

​Endpoints

​Supported providers

​Event schema

​Example: register a connection

​Example: push a batch (JSON array)

​Example: push a batch (NDJSON)

​Limits

​Status codes

​Best practices