/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API API Reference Analytics Overview

Analytics Overview

Track doc site usage with beacon endpoints and query aggregated analytics from the dashboard API.

4 min read

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

POST/v1/projects/{projectId}/analytics/pageview
NameDescription
pagePath:stringbodyRequired
Page path, e.g. /guides/quickstart.
visitorId:stringbody
Anonymous visitor ID.
sessionId:stringbody
Session ID for flow analysis.
referrer:stringbody
Document referrer.
duration:numberbody
Time on page in seconds.
deviceType:stringbody
desktop, mobile, or tablet.
previousPage:stringbody
Previous page path (navigation flow).
isBounce:booleanbody
Whether the visit was a bounce.
country:stringbody
Visitor country.
userAgent:stringbody
The browser's user agent.
browser:stringbody
Browser name.
os:stringbody
Operating system.
POST/v1/projects/{projectId}/analytics/search
NameDescription
query:stringbodyRequired
The search query.
resultCount:numberbodyRequired
Number of results returned. Zero-result queries surface in the gaps report.
clickedResult:stringbody
Path of the result the visitor clicked.
visitorId:stringbody
Anonymous visitor ID.

Track Chat Interaction

POST/v1/projects/{projectId}/analytics/chat
NameDescription
question:stringbodyRequired
The question asked.
confidence:numberbody
Answer confidence, 0–1.
feedback:stringbody
thumbs_up or thumbs_down.
citationCount:numberbody
Number of cited sources.
sessionId:stringbody
Chat session ID.
answerLength:numberbody
Length of the answer.
pagePath:stringbody
Page the question was asked from.
visitorId:stringbody
Anonymous visitor ID.

Track Playground Request

POST/v1/projects/{projectId}/analytics/playground
NameDescription
endpointPath:stringbodyRequired
The API path that was called.
method:stringbodyRequired
HTTP method.
statusCode:numberbody
Response status.
responseTimeMs:numberbody
Response time in milliseconds.
language:stringbody
Code sample language in use.
visitorId:stringbody
Anonymous visitor ID.
sessionId:stringbody
Session ID.

Track Funnel Event

POST/v1/projects/{projectId}/analytics/funnel
NameDescription
visitorId:stringbodyRequired
Anonymous visitor ID.
eventType:stringbodyRequired
landing, signup, first_api_call, active_usage or playground_use.
pagePath:stringbody
Page the event happened on.
metadata:objectbody
Any extra fields.

Dashboard Endpoints (auth required)

Most accept an optional ?days= query parameter (default 30) — the table says which.

Note

Session JWT and org membership required. Dashboard endpoints accept a signed-in session JWT only — a project API key (stx_…) gets 401. Being signed in is not enough: you must be a member of the org that owns {projectId}. A project you cannot see returns 404, and one you can see but are not a member of returns 403 with the forbidden code — see Errors. Any role (member, admin or owner) can read analytics, dismiss gaps and export. This does not apply to the beacon endpoints above, which are public by design.

EndpointReturns
GET /analytics/summaryTotals: views, visitors, searches, AI questions, plus an exportUrl (?days=) — see Get Summary
GET /analytics/top-pagesMost viewed pages (?days=, ?limit=20)
GET /analytics/views-over-timeDaily page views and visitors, plus 6-hour buckets up to 14 days (?days=) — see Get Views Over Time
GET /analytics/referrersTop 20 referrers with isNew (?days=) — see Get Referrers
GET /analytics/searchesPopular and zero-result searches, daily series and changes (?days=) — see Get Searches
GET /analytics/time-on-pageAverage, median and p90 seconds on page (?days=) — see Get Time on Page
GET /analytics/aiAI assistant analytics (?period= or ?days=) — see Get AI Insights
GET /analytics/gapsOpen documentation gaps, paginated (?limit=, ?offset=, ?source=reported|inferred) — see List Gaps
POST /analytics/gaps/{gapId}/dismissDismiss a gap — see Dismiss Gap
GET /analytics/exportDownload a CSV or JSON report (?days=, ?format=) — see Export Insights
GET /analytics/healthPer-page content health scores
GET /analytics/content-healthAggregate health with weekly history — see Content Health
GET /analytics/annotation-coverage@stx coverage and drift alerts — see Annotation Coverage
GET /analytics/bounce-rateBounce rate (?days=)
GET /analytics/navigation-flowWhere readers go next from a page (?pagePath= required, ?days=)
GET /analytics/devicesDevice breakdown (?days=)
GET /analytics/geoCountry breakdown (?days=)
GET /analytics/playground-usageAPI playground usage by endpoint (?days=, ?limit=20)
GET /analytics/broken-linksBroken links found on the site
GET /analytics/page-metadataPer-page readability and structure metadata
GET /analytics/api-coverageHow much of the API reference is documented
POST /analytics/health/computeRecompute content health now
GET /analytics/dx-funnelFunnel from landing to active usage (?days=)
GET /analytics/time-to-first-callTime from landing to first API call (?days=)
GET /analytics/dx-scoreDeveloper-experience score history (?limit=30)
POST /analytics/dx-score/computeRecompute the developer-experience score

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

Trend fields are optional

Period-over-period fields — daily, changes, history, trend, exportUrl and the like — are computed after the core figures. If one cannot be computed, it is left out of the response rather than failing the request, so treat each as optional. Unless a page says otherwise:

•
rates and shares are 0–100
•
a change in percent is a whole-number percentage against the previous window of the same length, and is left out when that window is empty
•
a change in points is the difference between two 0–100 rates

Example

bash
curl "https://api.syntext.dev/v1/projects/$PROJECT_ID/analytics/top-pages?days=7&limit=10" \
-H "Authorization: Bearer $SYNTEXT_JWT"
Note

The dashboard visualizes all of this under your project → Insights — the API exists for custom reporting and exports. See Insights for the feature guide.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext