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

# AI traffic endpoints

> Track visits from AI assistants, manage tracking sites, and pull AI traffic analytics via the REST API.

Base path: `/v1/ai-traffic`

AI traffic endpoints measure how many visitors reach your site from AI assistants like ChatGPT, Perplexity, Claude, and Gemini. Pair these routes with the lightweight tracking script (or a connected Google Analytics property) to power custom dashboards and reporting.

<Note>
  These routes are available on the public API using your `api-key` header, the same as every other `/v1` endpoint. See the [REST API overview](/api-reference/overview) for authentication and plan eligibility.
</Note>

<Warning>
  Detailed analytics — AI sources, traffic over time, and top pages — are available on paid plans. On free plans these fields are omitted and responses include `"restricted": true`. Summary totals remain available. See the [pricing page](https://www.krastie.ai/pricing).
</Warning>

## How tracking works

1. Create a tracking site to get a `siteKey` and a ready-to-paste script snippet.
2. Install the snippet on every page you want to measure (before `</head>`).
3. Query `GET /v1/ai-traffic/stats` to read aggregated AI traffic.

The snippet looks like this:

```html theme={null}
<script async src="https://api.krastie.ai/v1/ai-traffic/t.js" data-site="ks_YOUR_SITE_KEY"></script>
```

As an alternative to the script tag, you can connect Google Analytics as the data source — see [Google Analytics as a data source](#google-analytics-as-a-data-source).

## GET `/sites`

List the tracking sites in your workspace.

```bash theme={null}
curl https://api.krastie.ai/v1/ai-traffic/sites \
  -H "api-key: krastie_YOUR_KEY"
```

**Response (200):**

```json theme={null}
{
  "sites": [
    {
      "siteKey": "ks_abc123",
      "domain": "example.com",
      "name": "My site",
      "snippet": "<script async src=\"https://api.krastie.ai/v1/ai-traffic/t.js\" data-site=\"ks_abc123\"></script>"
    }
  ]
}
```

## POST `/sites`

Create a new tracking site. Returns the site with its generated `siteKey` and install snippet.

**Body:**

| Field | Type | Required | Description |
| - | - | - | - |
| `domain` | string | Yes | Website domain to track (e.g. `example.com`) |
| `name` | string | No | Friendly label for the site |

```bash theme={null}
curl -X POST https://api.krastie.ai/v1/ai-traffic/sites \
  -H "Content-Type: application/json" \
  -H "api-key: krastie_YOUR_KEY" \
  -d '{"domain": "example.com", "name": "My site"}'
```

**Response (200):**

```json theme={null}
{
  "site": {
    "siteKey": "ks_abc123",
    "domain": "example.com",
    "name": "My site",
    "snippet": "<script async src=\"https://api.krastie.ai/v1/ai-traffic/t.js\" data-site=\"ks_abc123\"></script>"
  }
}
```

## POST `/sites/ensure`

Ensure a default tracking site exists for the workspace. Useful when bootstrapping — it returns the existing site, creates one when possible, or signals that a domain is still required.

```bash theme={null}
curl -X POST https://api.krastie.ai/v1/ai-traffic/sites/ensure \
  -H "api-key: krastie_YOUR_KEY"
```

**Response (200):**

```json theme={null}
{
  "site": {
    "siteKey": "ks_abc123",
    "domain": "example.com",
    "name": "My site",
    "snippet": "<script async src=\"https://api.krastie.ai/v1/ai-traffic/t.js\" data-site=\"ks_abc123\"></script>"
  }
}
```

When no domain is known yet, the response asks you to create a site with `POST /sites`:

```json theme={null}
{
  "needsDomain": true
}
```

## GET `/stats`

Fetch aggregated AI traffic for a tracking site.

**Query parameters:**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `days` | integer | No | Lookback window in days. Common values: `7`, `30`, `90`. Defaults to `7`. |
| `siteKey` | string | No | Tracking site to query. Defaults to the workspace's primary site. |

```bash theme={null}
curl "https://api.krastie.ai/v1/ai-traffic/stats?days=30&siteKey=ks_abc123" \
  -H "api-key: krastie_YOUR_KEY"
```

**Response (200):**

```json theme={null}
{
  "summary": {
    "totalPageviews": 8420,
    "aiPageviews": 1247,
    "aiShare": 0.148,
    "sessions": 3891
  },
  "daily": [
    { "date": "2026-03-19", "total": 280, "ai": 42 },
    { "date": "2026-03-20", "total": 310, "ai": 48 }
  ],
  "sources": [
    { "source": "chatgpt", "count": 620 },
    { "source": "perplexity", "count": 312 },
    { "source": "claude", "count": 198 },
    { "source": "gemini", "count": 117 }
  ],
  "topPages": [
    { "path": "/pricing", "total": 420, "ai": 89 },
    { "path": "/docs", "total": 380, "ai": 76 }
  ],
  "source": "script",
  "restricted": false
}
```

On free plans, `daily`, `sources`, and `topPages` are omitted and `restricted` is `true`:

```json theme={null}
{
  "summary": {
    "totalPageviews": 8420,
    "aiPageviews": 1247,
    "aiShare": 0.148,
    "sessions": 3891
  },
  "restricted": true,
  "source": "script"
}
```

## Stats data model

| Field | Description |
| - | - |
| `summary.totalPageviews` | All pageviews in the selected window |
| `summary.aiPageviews` | Pageviews attributed to AI assistants |
| `summary.aiShare` | AI share of traffic as a decimal (`0.148` = 14.8%) |
| `summary.sessions` | Total sessions in the window |
| `daily[]` | Per-day series: `date`, `total`, `ai` (paid plans) |
| `sources[]` | AI referrers: `source`, `count` (paid plans) |
| `topPages[]` | Most-visited pages: `path`, `total`, `ai` (paid plans) |
| `source` | Data source for the response: `script` or `google_analytics` |
| `restricted` | `true` when detailed data is omitted for the current plan |

Exact field names may vary by API version. Treat responses as the source of truth for your integration.

## Google Analytics as a data source

Instead of the tracking script, you can pull AI traffic from a connected GA4 property. Connecting Google Analytics uses an OAuth flow completed in the Krastie app; once connected, these endpoints manage and read the integration.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/integrations/google-analytics/checkData` | Connection status and selected property |
| `GET` | `/v1/integrations/google-analytics/properties` | List available GA4 properties |
| `POST` | `/v1/integrations/google-analytics/property` | Select the GA4 property to read from |
| `GET` | `/v1/integrations/google-analytics/stats` | AI traffic stats from GA4 |
| `DELETE` | `/v1/integrations/google-analytics/disconnect` | Disconnect Google Analytics |

<Note>
  The OAuth connection step (`/v1/integrations/google-analytics/auth`) is a browser redirect and is completed in the app, not via the API.
</Note>

**Connection status:**

```bash theme={null}
curl https://api.krastie.ai/v1/integrations/google-analytics/checkData \
  -H "api-key: krastie_YOUR_KEY"
```

```json theme={null}
{
  "googleAnalytics": {
    "isConnected": true,
    "propertyId": "123456789",
    "propertyName": "Example.com - GA4"
  }
}
```

**List properties.** Pass `domain` to match by site URL and `autoSelect=1` to auto-pick a matching property:

```bash theme={null}
curl "https://api.krastie.ai/v1/integrations/google-analytics/properties?domain=example.com&autoSelect=1" \
  -H "api-key: krastie_YOUR_KEY"
```

```json theme={null}
{
  "properties": [
    {
      "propertyId": "123456789",
      "displayName": "Example.com - GA4",
      "account": "Example Inc",
      "domains": ["example.com"]
    }
  ],
  "autoSelected": {
    "propertyId": "123456789",
    "propertyName": "Example.com - GA4"
  },
  "matchDomain": "example.com"
}
```

**Select a property:**

```bash theme={null}
curl -X POST https://api.krastie.ai/v1/integrations/google-analytics/property \
  -H "Content-Type: application/json" \
  -H "api-key: krastie_YOUR_KEY" \
  -d '{"propertyId": "123456789", "propertyName": "Example.com - GA4"}'
```

**Read GA4 stats.** Returns the same [stats data model](#stats-data-model) with `"source": "google_analytics"`:

```bash theme={null}
curl "https://api.krastie.ai/v1/integrations/google-analytics/stats?days=30" \
  -H "api-key: krastie_YOUR_KEY"
```

## Workflow example

```bash theme={null}
# 1. Ensure a tracking site exists (or create one)
curl -X POST https://api.krastie.ai/v1/ai-traffic/sites \
  -H "Content-Type: application/json" \
  -H "api-key: krastie_YOUR_KEY" \
  -d '{"domain": "example.com", "name": "My site"}'

# 2. Install the returned snippet on your site, then read stats
curl "https://api.krastie.ai/v1/ai-traffic/stats?days=30&siteKey=ks_abc123" \
  -H "api-key: krastie_YOUR_KEY"
```

## Related endpoints

* [AI visibility endpoints](/api-reference/ai-visibility) — Measure mentions and citations in AI answers
* [Chat sessions](/api-reference/chat-sessions) — Assistant with visibility and traffic context


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.