Unlock Real‑Time Insights with Crazy Egg’s Headless Event API

What Is the Crazy Egg Headless Event API?

Crazy Egg is best known for its heat‑maps, scroll tracking, and click‑recordings. The Headless Event API takes those visual insights a step further – it lets you capture every user interaction programmatically and feed the data into your own dashboards, data warehouses, or marketing tools.

Why Go Headless?

• Real‑time data: No waiting for the Crazy Egg dashboard to refresh.
• Full control: Choose exactly which events to log and how they’re formatted.
• Integration friendly: Send events to Google Tag Manager, Segment, or a custom webhook.

Core Features of the API

1️⃣ Event Types

The API supports three primary event categories:

• Click events – element selector, X/Y coordinates, and timestamp.
• Scroll events – percentage of page scrolled, scroll depth, and viewport size.
• Custom events – any interaction you define (e.g., form submit, video play).

2️⃣ Payload Structure

{   "siteId": "YOUR_SITE_ID",   "event": "click",   "selector": ".cta-button",   "x": 124,   "y": 78,   "timestamp": 1725501234567,   "metadata": {     "userId": "12345",     "sessionId": "abcde"   } } 

All fields are optional except siteId and event. The metadata object is your playground for any additional context.

3️⃣ Authentication

Requests are secured with an API token that you generate in the Crazy Egg dashboard. Include it in the Authorization header as Bearer YOUR_TOKEN.

Step‑by‑Step Implementation

Step 1 – Get Your Token

1. Log into Crazy Egg.
2. Navigate to Account Settings → API Keys.
3. Click “Generate New Token” and copy the string.

Step 2 – Add the JavaScript Snippet

Place the standard Crazy Egg script on every page you want to track:

<script src="https://script.crazyegg.com/pages/scripts/XXXX.js" async></script> 

Replace XXXX with your site‑specific ID.

Step 3 – Capture an Event

Use the ce.track(eventName, payload) function that the script exposes:

document.querySelector('.cta-button').addEventListener('click', function(e) {   ce.track('click', {     selector: '.cta-button',     x: e.clientX,     y: e.clientY,     metadata: { userId: getUserId() }   }); }); 

Step 4 – Send to the Headless API

By default Crazy Egg stores the event in its SaaS platform. To forward it, attach a webhook in the dashboard:

1. Go to Integrations → Webhooks.
2. Add your endpoint URL (e.g., https://example.com/ce‑webhook).
3. Choose the event types you want to forward.

Alternatively, call the API directly from your front‑end:

fetch('https://api.crazyegg.com/v1/events', {   method: 'POST',   headers: {     'Content-Type': 'application/json',     'Authorization': 'Bearer YOUR_TOKEN'   },   body: JSON.stringify(eventPayload) }); 

Best Practices

• Throttle scroll events – send one every 200 ms to avoid overload.
• Batch custom events – collect 20 events and send them in a single request.
• Sanitize user data – never send passwords or personally identifying information.
• Test in dev mode – use the CE_DEBUG=1 query param to view raw payloads.

Common Use Cases

1. Conversion funnel analysis – Track button clicks, form submissions, and scroll depth to see where users drop off.
2. Personalized content triggers – Fire a modal when a user scrolls past 75% of a blog post.
3. Data lake ingestion – Pipe events into Snowflake or BigQuery for advanced cohort analysis.

FAQ

Do I still need the Crazy Egg dashboard?

No. The Headless API is designed for teams that want to own their analytics stack, but the dashboard remains useful for quick visual checks.

Is there a rate limit?

Crazy Egg permits up to 10 k events per minute per site. Exceeding this returns a 429 response.

Can I retroactively send historic data?

Only events captured after the token is generated are accepted. For historic data, import it directly into your warehouse.

What format does the webhook use?

Webhooks POST a JSON payload identical to the direct API structure.

Is the API GDPR‑compliant?

Yes, as long as you anonymize personal identifiers before sending them.

Conclusion

The Crazy Egg Headless Event API transforms visual heat‑maps into a programmable data stream. By capturing clicks, scrolls, and custom actions in real time, you can power dashboards, trigger personalized experiences, and feed a unified analytics platform—all while keeping full control over privacy and performance.

Ready to make your site’s behavior data truly yours? Start by generating an API token today and integrate the first event in minutes.

Call to Action

Download our free implementation checklist or book a 15‑minute strategy call to see how the Crazy Egg Headless Event API can boost your conversion rates.