# Site settings
Source: https://docs.ghostlyx.com/account/site-settings

Reference for all settings available on the GhostlyX site settings page.

## General

| Setting   | Description                                                                               |
| --------- | ----------------------------------------------------------------------------------------- |
| Site name | A display name for the site within the GhostlyX dashboard. Does not affect tracking.      |
| Domain    | The domain being tracked. Must match the `data-domain` attribute in your tracking script. |

## Notifications

| Setting                  | Description                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| Traffic spike alerts     | Sends an email when visitor count exceeds your configured threshold within a short window. |
| Spike threshold          | The number of visitors that triggers a spike notification.                                 |
| Spike notification email | The email address spike alerts are sent to. Defaults to the account owner's email.         |
| Weekly report            | Sends a weekly summary of your site's key metrics every Monday.                            |
| Monthly report           | Sends a monthly summary of your site's key metrics on the first of each month.             |

## Site health

### Hack detection

Toggle hack detection on or off. When enabling for the first time, GhostlyX immediately crawls your site to create the initial baseline.

Click **Re-baseline** after intentionally adding new third-party scripts to your site to update the known-good state.

See [Hack detection](/site-health/hack-detection) for full details.

## Shared dashboard

Toggle shared dashboard visibility on or off. When on, a read-only URL is generated that can be shared with anyone. Optionally set a password to restrict access.

See [Shared dashboards](/sharing/shared-dashboards) for full details.

## Danger zone

<Warning>
  Actions in the danger zone are irreversible.
</Warning>

### Reset statistics

Deletes all collected analytics data for this site. The tracking script continues to work and new data will be collected from the moment of the reset. Historical data cannot be recovered.

### Delete site

Permanently deletes the site and all associated data from GhostlyX, including analytics data, goals, funnels, recordings, and settings. The domain slot is freed and can be re-added.


# AI analyst
Source: https://docs.ghostlyx.com/ai/analyst

Ask questions about your site's analytics in plain language and get instant answers.

<Note>
  The AI analyst requires the **Business plan** or above.
</Note>

## What is the AI analyst?

The AI analyst is a conversational interface built into the GhostlyX dashboard. Ask questions about your analytics data in plain English and receive answers backed by your actual data.

## Example questions

* "What were my top pages last month?"
* "Did traffic drop after the deploy on May 3rd?"
* "Which country has the highest bounce rate this week?"
* "How many visitors came from organic search in the last 30 days?"
* "Is my conversion rate better on desktop or mobile?"
* "Show me pages where the bounce rate increased compared to last month."

## Accessing the analyst

Open the **AI** section in the dashboard sidebar and select **Analyst**. The analyst has access to all analytics data for the current site, including goals, funnels, sources, and device breakdowns.

## Data access

The analyst answers questions using your site's own analytics data. It can apply filters, compare date ranges, and cross-reference multiple dimensions in a single answer.

## Privacy

The AI analyst runs on GhostlyX's internal AI infrastructure. Your analytics data is not transmitted to any third-party AI provider or used to train external models.


# AI insights
Source: https://docs.ghostlyx.com/ai/insights

Automated weekly summaries of your site's analytics, delivered to your inbox and dashboard.

<Note>
  AI insights require the **Pro plan** or above.
</Note>

## What are AI insights?

GhostlyX automatically analyses your site's analytics data each week and generates a plain-language summary of what happened. Insights surface patterns that might otherwise require manual investigation.

## What insights include

Each weekly insight covers:

* **Traffic changes**: week-over-week and month-over-month changes in visitors and pageviews, with context on whether the change is significant
* **Top performing pages**: pages that drove the most growth in the period
* **Declining pages**: pages that lost significant traffic compared to the previous period
* **Unusual patterns**: traffic spikes, unexpected source changes, or anomalies worth investigating

## Where to find insights

Insights are delivered in two places:

1. **Email digest**: sent to account owners and admins each Monday morning, covering the previous week
2. **AI Insights tab**: visible in the dashboard under the **AI** section, showing the current and past weekly summaries

## Privacy

AI insights are generated using GhostlyX's internal AI infrastructure. Your raw analytics data is not sent to any third-party AI provider.

## Opting out

To stop receiving the weekly email digest, click **Unsubscribe** at the bottom of any insights email, or go to **Account Settings > Notifications** and disable the AI insights digest.


# MCP server
Source: https://docs.ghostlyx.com/ai/mcp-server

Connect AI coding assistants to your GhostlyX analytics data using the Model Context Protocol.

## What is the GhostlyX MCP server?

GhostlyX exposes a Model Context Protocol (MCP) server that allows AI coding assistants and agents to query your analytics data directly. Instead of copying numbers from the dashboard into a prompt, your AI assistant can retrieve live data on demand.

**MCP server URL:** `https://ghostlyx.com/mcp`

## Authentication

The MCP server uses API token authentication. Create a token in **Settings > API Tokens > Create token**. Tokens are read-only and have access to analytics data for all sites on your account.

See [API tokens](/developer/api-tokens) for full instructions.

## Compatible clients

* Claude Desktop
* Cursor
* Windsurf
* Any MCP-compatible client

## Available tools

| Tool                       | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `get_site_stats`           | Summary metrics (visitors, pageviews, bounce rate, duration) for a site and period |
| `get_top_pages`            | Top pages by pageviews with visitor counts                                         |
| `get_traffic_sources`      | Top referrers and traffic sources                                                  |
| `get_realtime_visitors`    | Current active visitors (last 5 minutes)                                           |
| `list_goals`               | All goals with completion counts and conversion rates                              |
| `get_funnel_stats`         | Step-by-step funnel conversion data                                                |
| `get_session_replay_stats` | Recording counts and UX signal summary                                             |
| `get_uptime_status`        | Current uptime status, response time, and 30-day uptime percentage                 |
| `manage_annotations`       | List or create annotations on the trend chart                                      |

## Configuration: Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json theme={"dark"}
{
  "mcpServers": {
    "ghostlyx": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ghostlyx.com/mcp"],
      "env": { "API_TOKEN": "your-token-here" }
    }
  }
}
```

Replace `your-token-here` with the API token you created in GhostlyX.

## Configuration: Cursor and Windsurf

Add the same JSON block to your MCP configuration file for those clients. Refer to the Cursor or Windsurf documentation for the exact file location.


# A/B testing
Source: https://docs.ghostlyx.com/analytics/ab-testing

Track A/B test variant performance using custom events and goals.

## How GhostlyX fits into A/B testing

GhostlyX does not serve variants or split traffic. Use your own A/B testing tool or feature flag system (Optimizely, LaunchDarkly, GrowthBook, or a custom implementation) to assign visitors to variants. GhostlyX then measures the conversion outcome for each variant.

## Instrumenting variants

When a visitor is assigned to a variant, fire a custom event with a property that identifies which variant they saw:

```js theme={"dark"}
ghostlyx('event', 'Experiment', { variant: 'A' })
```

For variant B:

```js theme={"dark"}
ghostlyx('event', 'Experiment', { variant: 'B' })
```

You can use any event name and any property name that makes sense for your experiment.

## Tracking conversions per variant

Fire a second custom event when the conversion you are measuring occurs. For example, if you are testing a pricing page and measuring sign-ups:

```js theme={"dark"}
// When the visitor signs up
ghostlyx('event', 'Sign up', { variant: 'A' })
```

## Comparing results in the dashboard

1. Create a [Custom event goal](/analytics/goals) for each event name you are using.
2. View the goal in the dashboard to see completion counts and conversion rates.
3. Filter the dashboard by variant property value to isolate each group.

Because GhostlyX is a measurement layer, you retain full control over the experiment design and statistical analysis. Use your A/B testing platform's built-in significance calculator, or export the raw counts and run your own statistical test.

## Compatible tools

GhostlyX works alongside any client-side or server-side A/B testing tool, including:

* Optimizely
* LaunchDarkly
* GrowthBook
* VWO
* Custom feature flag systems


# Annotations
Source: https://docs.ghostlyx.com/analytics/annotations

Mark significant dates on the analytics trend chart to give context to traffic changes.

## What are annotations?

Annotations are notes attached to a specific date. They appear as pins on the trend chart in the analytics dashboard, giving you and your team context for why traffic changed on a given day.

Common uses:

* Deployment or major feature release
* Marketing campaign launch or end
* Site outage or incident
* Significant blog post or press coverage
* Seasonal event or public holiday

## Creating an annotation

**From the chart:**

1. Hover over the date on the trend chart where you want to add a note.
2. Click the **+** icon that appears.
3. Type your note and click **Save**.

**From settings:**

1. Go to **Settings > Annotations**.
2. Click **Add annotation**.
3. Pick the date and enter your note.
4. Click **Save**.

## Viewing annotations

Annotations appear as small pins along the bottom of the trend chart. Hover over a pin to read the note. Annotations are visible to all team members who have access to the site.

## Editing and deleting

Go to **Settings > Annotations** to edit or delete existing annotations. Changes take effect immediately on the chart.

<Note>
  Annotations are available on all plans.
</Note>


# Custom events
Source: https://docs.ghostlyx.com/analytics/custom-events

Track user interactions beyond pageviews using the GhostlyX JavaScript API.

## Firing a custom event

Call the global `ghostlyx()` function after the tracking script has loaded:

```js theme={"dark"}
ghostlyx('event', 'Button clicked')
```

The event name is a free-form string. Choose names that are meaningful to your team. Event names are case-sensitive.

## Adding properties

Pass an object as the third argument to attach properties to the event:

```js theme={"dark"}
ghostlyx('event', 'Purchase', { revenue: 49.99, plan: 'pro' })
```

Properties must be strings or numbers. A maximum of 20 properties are supported per event. Properties appear in the goal detail view in the dashboard once a matching goal is created.

## Connecting events to goals

Events are only counted in the dashboard when a matching [Custom event goal](/analytics/goals) exists. Create a goal with the same event name in **Settings > Goals** to start seeing completions and conversion rates.

## SPA and deferred loading

If your script loads asynchronously, wrap event calls in a check to avoid errors before the script is ready:

```js theme={"dark"}
if (typeof ghostlyx === 'function') {
  ghostlyx('event', 'Sign up started')
}
```

## Server-side events

If you need to fire an event from your server (for example, after a payment is confirmed server-side), use the Events API instead of the JavaScript API. See [Server-side tracking](/developer/server-side-tracking) for details.


# Analytics dashboard
Source: https://docs.ghostlyx.com/analytics/dashboard

Understanding the metrics, filters, and charts on the GhostlyX analytics dashboard.

## Core metrics

The top of the dashboard shows five summary metrics for the selected date range:

| Metric          | Definition                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------ |
| Unique visitors | Individual visitors counted without cookies or fingerprinting. No personal data is stored. |
| Pageviews       | Total number of pages loaded or virtual pageview events fired.                             |
| Visits          | Groups of pageviews from the same visitor with no more than 30 minutes between them.       |
| Bounce rate     | Percentage of visits where only a single page was viewed.                                  |
| Visit duration  | Average time from first to last event in a visit.                                          |

## Date range

Use the date picker in the top-right corner to select a preset period or a custom range:

* **24h**: rolling 24 hours, broken down by hour
* **7d**: last 7 days
* **30d**: last 30 days
* **6mo**: last 6 months
* **12mo**: last 12 months
* **Custom**: pick any start and end date

## Trend graph

The trend graph shows visitor and pageview counts over time. Switch between daily, weekly, and monthly granularity using the toggle above the chart. Hover over any point to see exact numbers. [Annotations](/analytics/annotations) appear as pins on the chart.

## Top pages

The top pages table lists the most visited pages ranked by pageviews, with a visitor count for each. Click any row to filter the entire dashboard to traffic for that page.

## Traffic sources

The sources breakdown shows where your visitors came from:

* **Direct**: no referrer, or referrer stripped by the browser
* **Search**: organic search engines (Google, Bing, DuckDuckGo, etc.)
* **Referral**: other websites linking to you
* **Social**: social networks (Twitter/X, Facebook, LinkedIn, etc.)
* **Email**: email clients and newsletter links

Click any source to filter the dashboard to that traffic segment.

## Geographic, device, and technology breakdowns

Below the sources section you will find breakdowns by:

* **Countries**: top countries by visitor count
* **Devices**: Desktop, Mobile, Tablet
* **Browsers**: Chrome, Safari, Firefox, Edge, etc.
* **Operating systems**: Windows, macOS, iOS, Android, Linux, etc.

## Filters

You can filter the entire dashboard simultaneously by clicking any item in any breakdown table (page, source, country, device, browser, or OS). Active filters are shown as chips at the top of the dashboard. Remove a filter by clicking the X on the chip or clicking the same item again.

Filters are composable: for example, you can filter to visitors from Germany on mobile using Safari at the same time.


# Funnels
Source: https://docs.ghostlyx.com/analytics/funnels

Measure drop-off across multi-step user journeys with conversion funnels.

<Note>
  Funnels require the **Business plan** or above.
</Note>

## What is a funnel?

A funnel is an ordered sequence of steps that maps a visitor journey. GhostlyX shows you how many visitors entered the funnel, how many completed each step, and where they dropped off.

## Creating a funnel

1. Go to **Analytics > Funnels**.
2. Click **New funnel**.
3. Give the funnel a name.
4. Add steps in order. Each step must be an existing [Goal](/analytics/goals) (either a pageview goal or a custom event goal).
5. Click **Save**.

You can add as many steps as needed. Steps must be added in the order visitors are expected to complete them.

## Funnel metrics

For each step in the funnel you will see:

| Metric          | Definition                                                                       |
| --------------- | -------------------------------------------------------------------------------- |
| Visitors        | Number of unique visitors who reached this step                                  |
| Drop-off        | Visitors who completed the previous step but not this one                        |
| Drop-off rate   | Drop-off as a percentage of the previous step's visitors                         |
| Conversion rate | Visitors who completed this step as a percentage of those who entered the funnel |

The **overall conversion rate** is the percentage of visitors who entered step one and completed the final step.

## Setting up goals for funnel steps

Before building a funnel, create goals for each step you want to track:

* Use a **Pageview goal** for steps where the visitor lands on a specific URL (e.g. `/pricing`, `/checkout`, `/thank-you`).
* Use a **Custom event goal** for steps triggered by a JavaScript action (e.g. "Add to cart", "Form submitted").

See [Goals](/analytics/goals) for instructions on creating goals.


# Goals
Source: https://docs.ghostlyx.com/analytics/goals

Track conversions by setting up pageview and custom event goals.

## Goal types

GhostlyX supports two types of goals:

* **Pageview goal**: triggered when a visitor reaches a specific URL path
* **Custom event goal**: triggered when your code calls the GhostlyX JavaScript API with a matching event name

## Creating a pageview goal

1. Go to **Settings > Goals**.
2. Click **Add goal**.
3. Select **Pageview** as the goal type.
4. Enter the path to match, for example `/thank-you` or `/checkout/success`.
5. Click **Save**.

Paths support a `*` wildcard at the end. For example, `/blog/*` matches any URL that starts with `/blog/`.

## Creating a custom event goal

1. Go to **Settings > Goals**.
2. Click **Add goal**.
3. Select **Custom event** as the goal type.
4. Enter the event name exactly as it appears in your `ghostlyx('event', '...')` call.
5. Click **Save**.

Custom events must be instrumented in your site's JavaScript before the goal will record completions. See [Custom events](/analytics/custom-events) for how to fire events.

## Goal stats on the dashboard

Once a goal is created, it appears in the **Goals** section of the dashboard. For each goal you will see:

| Metric             | Definition                                                          |
| ------------------ | ------------------------------------------------------------------- |
| Completions        | Total number of times the goal was completed in the selected period |
| Unique completions | Completions counted once per visitor per day                        |
| Conversion rate    | Unique completions divided by unique visitors                       |

## Using goals as funnel steps

Goals can be added as steps in a funnel to measure drop-off across a multi-step journey. See [Funnels](/analytics/funnels) for details.


# Heatmaps
Source: https://docs.ghostlyx.com/behaviour/heatmaps

Visualise where visitors click and how far they scroll on your pages.

<Note>
  Heatmaps require the **Business plan** or above.
</Note>

## Click heatmaps

Click heatmaps show a colour-coded overlay on top of your page indicating where visitors clicked. Areas with more clicks appear warmer (red/orange). Areas with few or no clicks appear cooler (blue/grey).

Click heatmaps help you identify:

* Which calls to action are getting attention
* Whether visitors are clicking on non-interactive elements (potential dead clicks)
* How attention is distributed between competing elements

## Scroll heatmaps

Scroll heatmaps show what percentage of sessions reached each vertical point on the page. A score of 80% at a given point means 80% of sessions scrolled at least that far down.

Scroll heatmaps help you identify:

* Where visitors stop reading
* Whether important content is placed above or below the typical scroll depth
* The effective "fold" for your actual audience

## Viewing a heatmap

1. Go to **Analytics > Heatmaps**.
2. Select a page from the list. Pages are ranked by pageview volume.
3. Toggle between **Click** and **Scroll** heatmap views using the controls at the top.

## Data aggregation

Heatmap data is aggregated across all sessions that match the selected page URL. You cannot view heatmap data for an individual session. For individual session behaviour, use [Session replay](/behaviour/session-replay).

## URL matching

Heatmaps match on the URL path. Query strings and fragments are ignored by default. If your page has multiple URL variants (for example, with different query parameters), their click and scroll data is combined.


# Session replay
Source: https://docs.ghostlyx.com/behaviour/session-replay

Record and replay real visitor sessions to understand how people use your site.

<Note>
  Session replay requires the **Business plan** or above.
</Note>

## Privacy defaults

Session replay in GhostlyX is privacy-first by default:

* All text content is masked before capture. GhostlyX records layout and interaction patterns, not the actual text visitors type or read
* Images are masked
* No IP addresses are stored
* Only CSS and layout information is captured. No screenshots or video are transmitted

These defaults cannot be disabled. They are not a setting.

## Enabling session replay

1. Go to **Settings** for your site.
2. Toggle **Session replay** on.
3. Set a **sampling rate**. The default is **10%**. GhostlyX will record approximately 1 in 10 sessions. Increase this if you need more data; decrease it to reduce storage usage.
4. Save settings.

Recording begins for new sessions within a few minutes.

## The replay player

Open a recording from **Analytics > Sessions**. The player includes:

* **Timeline**: scrub to any point in the session
* **Playback speed**: 0.5x, 1x, 2x, 4x
* **Event log**: a sidebar listing every click, scroll, and navigation event with timestamps
* **UX signals**: highlights of rage clicks, dead clicks, U-turns, and JavaScript errors

## UX signals

| Signal     | Definition                                                      |
| ---------- | --------------------------------------------------------------- |
| Rage click | Three or more clicks in the same area within 1 second           |
| Dead click | A click on an element that triggers no response                 |
| U-turn     | Visitor navigates to a page and immediately navigates back      |
| JS error   | An unhandled JavaScript exception was thrown during the session |

## Filtering recordings

Filter the recordings list by UX signal, entry page, device type, country, or date range to find the sessions most relevant to what you are investigating.

## Retention

Recordings are retained for 90 days and automatically deleted after that period.


# API tokens
Source: https://docs.ghostlyx.com/developer/api-tokens

Create and manage API tokens for the GhostlyX REST API and MCP server.

## What API tokens are for

API tokens authenticate requests to the GhostlyX REST API and the [MCP server](/ai/mcp-server). They are required if you want to query your analytics data programmatically or connect an AI assistant to GhostlyX.

## Creating a token

1. Go to **Settings > API Tokens**.
2. Click **Create token**.
3. Give the token a descriptive name (for example, "Claude Desktop" or "CI reporting script").
4. Click **Create**.
5. Copy the token value immediately. It is shown only once.

<Warning>
  The token value is displayed once at creation. If you lose it, you will need to revoke the token and create a new one.
</Warning>

## Token scope

All tokens currently provide read-only access to analytics data for all sites on your account. Write access (for example, creating annotations) is also available through the MCP server using the same token.

There is no per-site token scoping at this time.

## Revoking a token

1. Go to **Settings > API Tokens**.
2. Click **Revoke** next to the token you want to remove.
3. Confirm the action.

Revocation is immediate. Any system using the revoked token will receive authentication errors until it is updated with a valid token.

## Security

* Store tokens in environment variables or a secrets manager. Never hardcode them in source code.
* Rotate tokens periodically, especially if a token may have been exposed.
* Revoke tokens that are no longer in use.


# Data import
Source: https://docs.ghostlyx.com/developer/data-import

Import historical analytics data from other platforms into GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## Supported sources

| Platform            | Guide                                                          |
| ------------------- | -------------------------------------------------------------- |
| Google Analytics 4  | [Import from GA4](/import/google-analytics-4)                  |
| Universal Analytics | [Import from Universal Analytics](/import/universal-analytics) |
| Plausible           | [Import from Plausible](/import/plausible)                     |
| Fathom              | [Import from Fathom](/import/fathom)                           |
| Matomo              | [Import from Matomo](/import/matomo)                           |
| Simple Analytics    | [Import from Simple Analytics](/import/simple-analytics)       |
| Generic CSV         | [Import from CSV](/import/csv)                                 |

## How imports work

1. Export a CSV file from your current analytics platform (see the platform-specific guides linked above).
2. Go to your site dashboard and click **Import Data**.
3. Select your source platform and upload the CSV file.
4. GhostlyX validates the file and queues the import.

Imports run in the background. Return to the **Import Data** page to monitor progress. Large imports can take several minutes.

## Blended data

Once an import is complete, the imported historical data is blended with GhostlyX-collected data in the dashboard. You can use the date range picker to view historical data alongside current data in the same chart.

Imported data is clearly marked in the dashboard so you can distinguish it from natively collected data.

## Limits

* Maximum file size: 100 MB
* File encoding: UTF-8
* One active import per site at a time

If your historical dataset is larger than 100 MB, split it into multiple files and import them sequentially.


# JavaScript API
Source: https://docs.ghostlyx.com/developer/javascript-api

Reference for the GhostlyX JavaScript tracking API available in the browser.

## Overview

After the GhostlyX script loads, the global `ghostlyx()` function is available in the browser. Use it to track custom events, fire manual pageviews, and manage visitor opt-out preferences.

## Track a custom event

```js theme={"dark"}
ghostlyx('event', 'Event Name')
```

## Track a custom event with properties

```js theme={"dark"}
ghostlyx('event', 'Purchase', { revenue: 49.99, plan: 'pro' })
```

Properties must be strings or numbers. A maximum of 20 properties are supported per event.

## Track a manual pageview (SPAs)

For single-page applications where you manage routing manually and are not using `data-spa="auto"`:

```js theme={"dark"}
ghostlyx('pageview')
```

## Track a manual pageview with a custom URL

```js theme={"dark"}
ghostlyx('pageview', { url: '/virtual/page' })
```

Use this to track virtual pages or to override the URL that GhostlyX records for the current view.

## Opt a visitor out

Stores an opt-out preference in the visitor's localStorage. While opted out, no data is sent to GhostlyX for that visitor.

```js theme={"dark"}
ghostlyx('opt-out')
```

## Opt a visitor back in

```js theme={"dark"}
ghostlyx('opt-in')
```

## Check opt-out status

Returns `true` if the current visitor is opted out, `false` otherwise.

```js theme={"dark"}
ghostlyx('is-opted-out')
```

## Self-exclusion

To exclude your own visits while developing or testing, call `ghostlyx('opt-out')` in your browser console. This stores a preference in localStorage and no data will be sent from that browser until you call `ghostlyx('opt-in')`.


# Server-side tracking
Source: https://docs.ghostlyx.com/developer/server-side-tracking

Send events to GhostlyX from your server using the Events API.

## When to use server-side tracking

Use the Events API when:

* You need to record a conversion that happens entirely on the server (for example, a payment confirmation received via webhook)
* You are building a server-rendered application without a browser front-end
* You want to guarantee an event is recorded even if the visitor's browser blocks JavaScript

## Endpoint

```
POST https://ghostlyx.com/api/event
```

## Headers

| Header         | Value                                    |
| -------------- | ---------------------------------------- |
| `Content-Type` | `application/json`                       |
| `User-Agent`   | The visitor's original User-Agent string |

## Request body

```json theme={"dark"}
{
  "domain": "yourdomain.com",
  "name": "Purchase",
  "url": "https://yourdomain.com/checkout/success",
  "props": {
    "plan": "pro",
    "revenue": 49.99
  }
}
```

| Field    | Required | Description                                          |
| -------- | -------- | ---------------------------------------------------- |
| `domain` | Yes      | The domain as configured in GhostlyX                 |
| `name`   | Yes      | The event name. Use `pageview` to record a pageview. |
| `url`    | Yes      | The full URL where the event occurred                |
| `props`  | No       | Object of string or number properties                |

## Response

`202 Accepted` on success. No response body.

## Example: cURL

```bash theme={"dark"}
curl -X POST https://ghostlyx.com/api/event \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 ..." \
  -d '{
    "domain": "yourdomain.com",
    "name": "Purchase",
    "url": "https://yourdomain.com/checkout/success",
    "props": { "plan": "pro", "revenue": 49.99 }
  }'
```

## Connecting to goals

Server-side events are matched to [Custom event goals](/analytics/goals) by event name, the same as client-side events.


# Installation
Source: https://docs.ghostlyx.com/getting-started/installation

Add the GhostlyX tracking script to your site in under a minute.

## Add the script tag

Paste the following snippet before the closing `</head>` tag on every page you want to track:

```html theme={"dark"}
<script defer data-domain="yourdomain.com" src="https://ghostlyx.com/js/script.js"></script>
```

Replace `yourdomain.com` with the domain you configured when you created your site in GhostlyX. The value must match exactly. No protocol, no trailing slash.

## Platform guides

The snippet works on any site that serves HTML. Common setups:

| Platform    | Where to add the snippet                                                |
| ----------- | ----------------------------------------------------------------------- |
| Plain HTML  | Before `</head>` in your HTML file                                      |
| WordPress   | Appearance > Theme Editor > `header.php`, or use a header/footer plugin |
| Webflow     | Project Settings > Custom Code > Head code                              |
| Shopify     | Online Store > Themes > Edit code > `theme.liquid`                      |
| Next.js     | `pages/_document.js` or `app/layout.tsx` `<head>` section               |
| Squarespace | Settings > Advanced > Code Injection > Header                           |

## Single-page applications

For React, Vue, Angular, and other client-side routing frameworks, add the `data-spa="auto"` attribute so GhostlyX tracks route changes automatically:

```html theme={"dark"}
<script defer data-domain="yourdomain.com" src="https://ghostlyx.com/js/script.js" data-spa="auto"></script>
```

## Privacy

No cookies are set. No personal data is collected. The script does not use localStorage or fingerprinting of any kind. You do not need a cookie consent banner for the GhostlyX script.

## Verify installation

1. Open your site in a browser.
2. Open the GhostlyX dashboard and go to the **Real-time** tab.
3. Within 60 seconds you should see your visit counted as an active visitor.

<Note>
  If you do not see data after 60 seconds, check that the `data-domain` value matches the domain in your site settings exactly, and that the script tag is present in the rendered HTML (not just the source template).
</Note>


# Overview
Source: https://docs.ghostlyx.com/getting-started/overview

GhostlyX is privacy-first website analytics built for teams who want accurate data without compromising visitor privacy.

## What is GhostlyX?

GhostlyX is a suite of website intelligence tools designed around a single principle: you can have complete, accurate analytics without collecting personal data. There are no cookies, no fingerprinting, and no individual user profiles.

One script tag is all you need. Data appears in your dashboard within seconds of installation.

## Features

### Analytics

Track unique visitors, pageviews, visits, bounce rate, and average session duration. Break down traffic by source, country, device, browser, and OS. Set up conversion goals, multi-step funnels, and custom events.

[Go to Analytics dashboard](/analytics/dashboard)

### Uptime monitoring

GhostlyX checks your site every 60 seconds from multiple locations. When your site goes down, you are notified immediately by email, Slack, or webhook.

[Go to Uptime monitoring](/site-health/uptime-monitoring)

### Hack detection

GhostlyX scans your site's HTML on a schedule and alerts you when a new script or resource appears that was not present when you enabled the feature. Catches cryptocurrency miners, ad injectors, and data exfiltration scripts early.

[Go to Hack detection](/site-health/hack-detection)

### Session replay

Record and replay real visitor sessions to understand how people interact with your site. Privacy is on by default: text and images are masked, and no IP addresses are stored.

[Go to Session replay](/behaviour/session-replay)

### Heatmaps

Visualise where visitors click and how far they scroll on any page. Data is aggregated across all sessions for the selected URL.

[Go to Heatmaps](/behaviour/heatmaps)

### AI insights

Weekly summaries of traffic changes, top pages, and unusual patterns delivered to your inbox and visible in the dashboard. Ask the AI analyst questions about your data in plain language.

[Go to AI insights](/ai/insights)

## Compliance

GhostlyX is GDPR and CCPA compliant by design. Because no personal data is collected, no consent banner is required under GDPR. Data is stored in EU data centres.

## Next step

[Install the tracking script](/getting-started/installation) on your site and you will have live data in under a minute.


# Privacy
Source: https://docs.ghostlyx.com/getting-started/privacy

How GhostlyX handles data and why no consent banner is required.

## No cookies, no fingerprinting

GhostlyX does not set any cookies. It does not use localStorage, IndexedDB, or any other persistent storage in the visitor's browser. It does not fingerprint visitors using canvas, WebGL, fonts, or any other browser characteristics.

## No IP address storage

GhostlyX does not store IP addresses. No IP address is ever written to disk or stored in any database.

## Aggregated data only

All metrics in GhostlyX are aggregated. There are no individual visitor profiles, no session identifiers tied to a person, and no way to reconstruct a specific visitor's journey through your site.

## GDPR

Because GhostlyX does not process personal data as defined by the GDPR, it does not trigger the requirement for a lawful basis or consent under Article 6. You do not need a cookie consent banner or opt-in mechanism for the GhostlyX tracking script.

Data is stored in EU data centres and is not transferred outside the EEA.

## CCPA

GhostlyX does not sell or share personal data. Because no personal data is collected, GhostlyX does not create obligations under the CCPA for the data it collects on your behalf.

## Data retention

Aggregated analytics data is retained for as long as your account is active. You can reset or delete all data for a site at any time from Site Settings > Danger zone.

## Sub-processors

GhostlyX does not send your analytics data to any third-party analytics or advertising provider. AI features are powered by GhostlyX's internal infrastructure; raw analytics data is not sent to third-party AI providers.


# Import from CSV
Source: https://docs.ghostlyx.com/import/csv

Import historical pageview data using the generic CSV format.

<Note>
  Data import requires the **Scale plan**.
</Note>

## When to use the CSV import

Use the generic CSV import when your analytics platform is not in the list of supported sources, or when you have custom-generated pageview data you want to blend into GhostlyX.

## Required columns

Your CSV must have at least two columns: one for the page path and one for the pageview count.

**Accepted path column names:**

* `path`
* `page`
* `pathname`
* `url`
* `page_path`
* `page path`
* `Page path and screen class`

**Accepted pageviews column names:**

* `pageviews`
* `views`
* `hits`
* `page_views`
* `Pageviews`
* `Unique Pageviews`

Column names are case-insensitive.

## File requirements

| Requirement       | Detail   |
| ----------------- | -------- |
| Encoding          | UTF-8    |
| Maximum file size | 100 MB   |
| Delimiter         | Comma    |
| Header row        | Required |

## Number formatting

Numbers with thousands separators are handled automatically. Both `1234` and `1,234` are accepted as valid pageview counts.

## Example file

```csv theme={"dark"}
path,pageviews
/,12450
/blog,4320
/blog/getting-started,1890
/pricing,980
/about,540
```

## Step-by-step

1. Prepare your CSV file with the correct columns and encoding.
2. Go to your site dashboard and click **Import Data**.
3. Select **Generic CSV**.
4. Upload your file.
5. GhostlyX will preview the column mapping. Confirm it looks correct.
6. Click **Start import**.


# Import from Fathom
Source: https://docs.ghostlyx.com/import/fathom

Migrate your Fathom Analytics historical pageview data to GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## Step 1: Export from Fathom

1. In Fathom, go to your site's **Settings**.
2. Scroll to the **Data Export** section.
3. Select the date range you want to export.
4. Click **Export CSV**.

## Step 2: Upload to GhostlyX

1. Go to your site dashboard and click **Import Data**.
2. Select **Fathom**.
3. Upload the CSV file.
4. Click **Start import**.

## Column mapping

| Fathom column | GhostlyX field |
| ------------- | -------------- |
| `pathname`    | Page path      |
| `pageviews`   | Pageviews      |

## Notes

* If you have a large date range, consider exporting in yearly chunks and importing each file separately to stay within the 100 MB file size limit.
* Fathom exports only aggregate pageview counts per path, not individual session data. This is compatible with GhostlyX's import format.


# Import from Google Analytics 4
Source: https://docs.ghostlyx.com/import/google-analytics-4

Migrate your GA4 historical pageview data to GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## Step 1: Export from GA4

**Option A: Explorations export (recommended for most sites)**

1. In Google Analytics 4, go to **Explore**.
2. Create a **Blank exploration**.
3. Add the dimension **Page path and screen class**.
4. Add the metric **Views**.
5. Set the date range to cover the full period you want to import.
6. Click the export icon and choose **CSV**.

**Option B: BigQuery export (for large datasets)**

If your site has millions of pageviews, use the GA4 BigQuery export to avoid row limits in the Explorations UI. Export the data and format it as a CSV with columns `Page path and screen class` and `Views`.

## Step 2: Upload to GhostlyX

1. Go to your site dashboard and click **Import Data**.
2. Select **Google Analytics 4**.
3. Upload the CSV file.
4. Click **Start import**.

## Column mapping

| GA4 column                 | GhostlyX field |
| -------------------------- | -------------- |
| Page path and screen class | Page path      |
| Views                      | Pageviews      |

## Notes

* GA4 does not export unique visitors per page in the standard Explorations export. Imported data will show pageviews only; visitor counts for historical data will not be available.
* Query parameters are included in the page path column from GA4. GhostlyX will import them as-is.


# Import from Matomo
Source: https://docs.ghostlyx.com/import/matomo

Migrate your Matomo historical pageview data to GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## Step 1: Export from Matomo

1. In Matomo, go to **Behavior > Pages**.
2. Set the date range to cover the full period you want to import.
3. Scroll to the bottom of the table and click **Export**.
4. Choose **CSV** as the export format.

## Step 2: Upload to GhostlyX

1. Go to your site dashboard and click **Import Data**.
2. Select **Matomo**.
3. Upload the CSV file.
4. Click **Start import**.

## Column mapping

| Matomo column | GhostlyX field  |
| ------------- | --------------- |
| `Label`       | Page path (URL) |
| `Pageviews`   | Pageviews       |

## Notes

* Matomo's **Label** column contains the full URL of the page. GhostlyX will extract the path from the URL during import.
* If your Matomo report has more rows than the UI allows in a single page, adjust the **Display rows** setting to maximum before exporting.
* Matomo may include subdomain information in the Label column depending on your configuration. GhostlyX strips the domain and retains only the path.


# Import from Plausible
Source: https://docs.ghostlyx.com/import/plausible

Migrate your Plausible Analytics historical pageview data to GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## Step 1: Export from Plausible

1. In Plausible, go to your site's **Settings**.
2. Scroll to **Import & Export**.
3. Under **Export data**, click **Export to CSV**.
4. Save the downloaded ZIP or CSV file.

The export contains multiple CSV files. Use the **pages** export file, which is typically named `pages_YYYY-MM-DD_YYYY-MM-DD.csv`.

## Step 2: Upload to GhostlyX

1. Go to your site dashboard and click **Import Data**.
2. Select **Plausible**.
3. Upload the pages CSV file.
4. Click **Start import**.

## Column mapping

| Plausible column | GhostlyX field |
| ---------------- | -------------- |
| `page`           | Page path      |
| `pageviews`      | Pageviews      |

## Notes

* Upload only the pages CSV from the Plausible export, not the full ZIP file.
* Plausible's export format is straightforward and typically imports without issues.


# Import from Simple Analytics
Source: https://docs.ghostlyx.com/import/simple-analytics

Migrate your Simple Analytics historical pageview data to GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## Step 1: Export from Simple Analytics

1. In Simple Analytics, open your site dashboard.
2. Click **Export**.
3. Choose **Pages CSV**.

## Step 2: Upload to GhostlyX

1. Go to your site dashboard and click **Import Data**.
2. Select **Simple Analytics**.
3. Upload the CSV file.
4. Click **Start import**.

## Column mapping

| Simple Analytics column | GhostlyX field |
| ----------------------- | -------------- |
| `path`                  | Page path      |
| `pageviews`             | Pageviews      |

## Notes

* Simple Analytics exports a clean CSV that imports without any preprocessing needed.
* If you export data in multiple files (for example, split by year), import each file separately. GhostlyX will merge the data.


# Import from Universal Analytics
Source: https://docs.ghostlyx.com/import/universal-analytics

Migrate your Universal Analytics historical pageview data to GhostlyX.

<Note>
  Data import requires the **Scale plan**.
</Note>

## About Universal Analytics exports

Universal Analytics stopped collecting new data on July 1, 2023. However, the UA interface and its export functionality remain available, so you can still export your historical data.

## Step 1: Export from Universal Analytics

1. In Universal Analytics, go to **Behavior > Site Content > All Pages**.
2. Set the date range to cover the full period you want to import.
3. Scroll to the bottom of the table and set the number of rows to show as many rows as possible.
4. Click **Export** and choose **CSV**.

## Step 2: Upload to GhostlyX

1. Go to your site dashboard and click **Import Data**.
2. Select **Universal Analytics**.
3. Upload the CSV file.
4. Click **Start import**.

## Column mapping

| UA column | GhostlyX field |
| --------- | -------------- |
| Page      | Page path      |
| Pageviews | Pageviews      |

## Notes

* The exported CSV from UA includes a header block with report metadata before the data rows. GhostlyX handles this automatically.
* If your report contains more rows than the UA interface allows in a single export, split the export by date range and import each file separately.


# Shared dashboards
Source: https://docs.ghostlyx.com/sharing/shared-dashboards

Share a read-only view of your analytics with clients or the public.

## What is a shared dashboard?

A shared dashboard is a read-only URL that gives anyone who has it access to a subset of your analytics data, without requiring a GhostlyX account. Use it to share data with clients, stakeholders, or the public.

## Creating a shared dashboard

1. Go to **Settings** for your site.
2. Under **Shared dashboard**, toggle visibility on.
3. Optionally set a **password** to restrict access to people who know the password.
4. Copy the generated URL and share it.

## What is included

The shared dashboard shows:

* Core metrics (visitors, pageviews, visits, bounce rate, duration)
* Top pages
* Traffic sources
* Countries, devices, browsers, OS
* Goal conversion rates

## What is not included

The following are never visible on a shared dashboard:

* Session recordings
* Heatmaps
* A/B test details
* Hack detection status
* Site settings
* Billing information
* API tokens

## Revoking access

Disable the toggle in **Settings > Shared dashboard**. The URL will immediately return a 404. Re-enabling generates a new URL. The old URL does not become active again.

<Warning>
  Revoking a shared dashboard URL is immediate and permanent. Anyone using the old URL will lose access instantly. If you re-enable sharing, a new URL is generated.
</Warning>


# Team members
Source: https://docs.ghostlyx.com/sharing/team-members

Invite team members and manage their access to your GhostlyX sites.

<Note>
  Team members require the **Pro plan** or above. Seat limits apply by plan.
</Note>

## Roles

| Role   | Permissions                                                                 |
| ------ | --------------------------------------------------------------------------- |
| Owner  | Full access to all settings, billing, and team management. One per account. |
| Admin  | Full access to site settings and team management. Cannot change billing.    |
| Viewer | Read-only access to analytics dashboards. Cannot change any settings.       |

## Inviting a team member

1. Go to **Account Settings > Team**.
2. Click **Invite member**.
3. Enter the person's email address and select their role.
4. Click **Send invite**.

The person will receive an email invitation. They must accept within **72 hours** or the invitation expires. You can resend an expired invitation from the Team settings page.

## Seat limits

| Plan       | Maximum seats  |
| ---------- | -------------- |
| Starter    | 1 (owner only) |
| Pro        | 3              |
| Business   | 10             |
| Enterprise | Unlimited      |

If you need more seats than your plan allows, upgrade your plan or contact support.

## Removing a team member

1. Go to **Account Settings > Team**.
2. Click **Remove** next to the member you want to remove.
3. Confirm the action.

Removed members lose access immediately.

## Changing a role

Click the role dropdown next to any team member in **Account Settings > Team** to change their role. The change takes effect immediately.


# White label
Source: https://docs.ghostlyx.com/sharing/white-label

Remove GhostlyX branding from shared dashboards and use your own brand and domain.

<Note>
  White label requires the **Business plan** or above.
</Note>

## What white label includes

* **Custom logo**: replace the GhostlyX logo with your own on shared dashboards
* **Brand name**: displayed in the browser tab and page title of shared dashboards
* **Remove "Powered by GhostlyX"**: the attribution badge at the bottom of shared dashboards is hidden
* **Custom domain**: serve shared dashboards from your own domain instead of `ghostlyx.com`

## Configuring white label

Go to **Settings > White label**:

1. Upload your logo (SVG or PNG, recommended minimum 120px wide).
2. Enter your brand name.
3. Optionally set a custom domain (see below).
4. Save settings.

Changes apply immediately to all shared dashboard URLs for sites on your account.

## Custom domain setup

To serve shared dashboards from your own domain:

1. Enter your chosen subdomain in **Settings > White label > Custom domain** (for example, `analytics.yourcompany.com`).
2. Add a CNAME record in your DNS provider pointing that subdomain to `whitelabel.ghostlyx.com`.
3. Click **Verify** in the settings page. GhostlyX will check that the DNS record is in place.
4. SSL is provisioned automatically once verification passes.

DNS propagation can take up to 24 hours, though it is usually much faster.

<Note>
  Custom domain white labelling requires a Business plan. DNS changes must be made by whoever manages your DNS. GhostlyX cannot make DNS changes on your behalf.
</Note>


# Hack detection
Source: https://docs.ghostlyx.com/site-health/hack-detection

Detect injected scripts and malware by monitoring your site's HTML for unexpected changes.

<Note>
  Hack detection requires the **Business plan** or above.
</Note>

## How it works

When you enable hack detection, GhostlyX scans your site and records all third-party scripts and external resources present at that point. This becomes your **baseline** (the known-good state of your site).

GhostlyX then monitors your site on a regular schedule. If anything new appears that was not in the baseline, an alert is sent.

## Threats detected

Hack detection is designed to catch:

* Cryptocurrency mining scripts
* Ad injection scripts
* Malicious redirects
* Data exfiltration scripts (card skimmers, credential harvesters)
* Any other third-party script that was not present when you set up the baseline

## Enabling hack detection

1. Go to **Settings** for your site.
2. Toggle **Hack detection** on.
3. GhostlyX immediately crawls your site to create the initial baseline.
4. Save settings.

## Updating the baseline

When you intentionally add a new third-party script (for example, a new chat widget or analytics tool), GhostlyX will alert you on the next scan because it is not in the baseline. After confirming the script is legitimate:

1. Go to **Settings**.
2. Click **Re-baseline** under Hack detection.
3. GhostlyX re-crawls and updates the baseline to include the new script.

<Warning>
  Only re-baseline after you have verified that any new scripts on your site are intentional and legitimate. Re-baselining after an actual compromise would mark malicious scripts as safe.
</Warning>

## Notification channels

Hack detection alerts are sent through the same notification channels as uptime alerts. Configure them in **Settings > Notifications**.


# Uptime monitoring
Source: https://docs.ghostlyx.com/site-health/uptime-monitoring

Automatic uptime checks with instant alerts when your site goes down.

## How it works

GhostlyX sends an HTTP GET request to your site every 60 seconds. If consecutive checks return a non-successful status code, an incident is opened and you are notified.

**Status codes:**

* **200-399**: site is considered up
* **400 and above, connection errors, timeouts**: site is considered down

## Enabling uptime monitoring

1. Go to **Settings** for your site.
2. Toggle **Uptime monitoring** on.
3. Optionally change the **Monitor URL**. By default it checks your site's root (`/`). Change this to a specific path if you want to monitor a particular endpoint.
4. Save settings.

Monitoring begins within 60 seconds of enabling.

## Notifications

| Channel | Available on            |
| ------- | ----------------------- |
| Email   | All plans               |
| Slack   | Pro plan and above      |
| Webhook | Business plan and above |

Configure notification channels in **Settings > Notifications**.

## Dashboard

The **Uptime** section of the site dashboard shows:

* Current status (Up / Down / Incident)
* 30-day uptime percentage
* Average response time (last 30 days)
* Incident history with start time, end time, and duration

## Public status page

Each site monitored by GhostlyX gets a public status page at:

```
https://ghostlyx.com/status/your-domain
```

Share this URL with your users or customers so they can check your site's status without contacting support.