---
title: Analytics Overview
description: "Track doc site usage with beacon endpoints and query aggregated analytics from the dashboard API."
---

# Analytics API

The analytics API has two halves:

1. **Beacon endpoints** — public, high-volume endpoints doc sites call to record page views, searches, and chat interactions. Deployed doc sites include the tracking beacon automatically; you only call these yourself for custom integrations.
2. **Dashboard endpoints** — authenticated endpoints that return aggregated metrics.

## Beacon Endpoints (public, no auth)

All beacons return `202 Accepted` immediately and process asynchronously.

### Track Page View

<Endpoint method="POST" path="/v1/projects/{projectId}/analytics/pageview" />

<ParamField body="pagePath" type="string" required>Page path, e.g. `/guides/quickstart`.</ParamField>
<ParamField body="visitorId" type="string">Anonymous visitor ID.</ParamField>
<ParamField body="sessionId" type="string">Session ID for flow analysis.</ParamField>
<ParamField body="referrer" type="string">Document referrer.</ParamField>
<ParamField body="duration" type="number">Time on page in seconds.</ParamField>
<ParamField body="deviceType" type="string">`desktop`, `mobile`, or `tablet`.</ParamField>
<ParamField body="previousPage" type="string">Previous page path (navigation flow).</ParamField>
<ParamField body="isBounce" type="boolean">Whether the visit was a bounce.</ParamField>

### Track Search

<Endpoint method="POST" path="/v1/projects/{projectId}/analytics/search" />

<ParamField body="query" type="string" required>The search query.</ParamField>
<ParamField body="resultCount" type="number" required>Number of results returned. Zero-result queries surface in the gaps report.</ParamField>
<ParamField body="clickedResult" type="string">Path of the result the visitor clicked.</ParamField>

### Track Chat Interaction

<Endpoint method="POST" path="/v1/projects/{projectId}/analytics/chat" />

<ParamField body="question" type="string" required>The question asked.</ParamField>
<ParamField body="confidence" type="number">Answer confidence, 0–1.</ParamField>
<ParamField body="feedback" type="string">`thumbs_up` or `thumbs_down`.</ParamField>
<ParamField body="citationCount" type="number">Number of cited sources.</ParamField>

## Dashboard Endpoints (auth required)

All accept an optional `?days=30` query parameter (default 30).

| Endpoint | Returns |
|----------|---------|
| `GET /analytics/summary` | Totals: views, visitors, searches, AI questions — see [Get Summary](/api-reference/analytics/summary) |
| `GET /analytics/top-pages` | Most viewed pages (`?limit=20`) |
| `GET /analytics/views-over-time` | Daily page view series |
| `GET /analytics/searches` | Popular searches + zero-result queries |
| `GET /analytics/gaps` | Documentation gaps detected from AI chat |
| `GET /analytics/health` | Per-page content health scores |
| `GET /analytics/content-health` | Aggregate health — see [Content Health](/api-reference/analytics/content-health) |
| `GET /analytics/annotation-coverage` | `@stx` coverage — see [Annotation Coverage](/api-reference/analytics/annotation-coverage) |

All are relative to `/v1/projects/{projectId}`.

## Example

```bash
curl "https://api.syntext.dev/v1/projects/prj_abc123/analytics/top-pages?days=7&limit=10" \
  -H "Authorization: Bearer stx_abc12345_..."
```

<Note>
The dashboard at [syntext.dev](https://syntext.dev) visualizes all of this — the API exists for custom reporting and exports. See [Analytics & Insights](/platform/analytics) for the feature guide.
</Note>