---
title: "Analytics"
description: "Cookieless visitor analytics for every page that shows your articles.  No cookie or storage id: a visitor is a hash under a daily salt. Hosted blogs carry the script; elsewhere paste the `snippet` from `GET /analytics/setup` into `<head>`. The collector answers 202 to every event, so verify with `POST /analytics/install-check`. Script attributes, CSP and exclusions: https://writavo.com/docs/analytics."
canonical: "https://writavo.com/docs/api/analytics"
last-updated: "2026-09-30"
---

# Analytics

Cookieless visitor analytics for every page that shows your articles.

No cookie or storage id: a visitor is a hash under a daily salt. Hosted blogs carry the script;
elsewhere paste the `snippet` from `GET /analytics/setup` into `<head>`. The collector answers
202 to every event, so verify with `POST /analytics/install-check`. Script attributes, CSP and
exclusions: https://writavo.com/docs/analytics.

Base URL: `https://api.writavo.com/v1`

### GET /analytics/setup

Read the analytics setup and install status

- **Operation id**: `getAnalyticsSetup`
- **Scope**: `insights:read`
- **Permission**: `analytics.view`
- **Rate limit class**: read
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: no

Everything needed to install visitor analytics and confirm it works: the Site's public
`site_id`, the ready-made `snippet` to paste inside `<head>` on every page that shows your
articles, whether collecting is on, the domains whose visits count (`allowed_domains`: the
primary domain and its subdomains, verified custom domains, reverse-proxy targets and your
`extra_domains`), and `install`: when the last event arrived and from which page, how many
arrived in the last 24 hours, and the hosts whose visits were turned away because they are
not on the list.

The snippet always points at the public collector (`collector_origin`,
`https://blog.writavo.com` in production), never at a development address. Hosted Writavo
blogs carry it automatically. To check a page, use `POST /analytics/install-check`.

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | AnalyticsSetup | The setup. |
| 401 | - | `INVALID_API_KEY`, `API_KEY_REVOKED` or `API_KEY_EXPIRED`: no key, or an unusable one. It never distinguishes "no such key" from "wrong key". |
| 403 | - | `INSUFFICIENT_SCOPE`. The key lacks this operation's scope, or its creator's permissions no longer cover it. Another Site's object is always 404, never this. A 403 may also be: - `AGENT_ACCESS_DISABLED` - AI agent access is turned off. - `APPROVAL_DENIED` - a person denied this action. - `FORBIDDEN` (organisation, team, settings) - a change no scope allows, such as an AI agent changing the access of the person it acts for, anything about ownership, or a setting only a person may change. The message says what to do instead. |
| 429 | - | `RATE_LIMIT_EXCEEDED`. Back off and honour `Retry-After`. Limits are per key, per minute, by endpoint class. The two device sign-in endpoints take no key, so they are limited per IP address. \| Class \| Endpoints \| Limit \| \|---\|---\|---\| \| read \| every GET \| 600 per minute \| \| write \| POST, PATCH and DELETE on content, taxonomy, keys, webhooks, the content plan, formats and prompts, settings, delivery, SEO curation, the team and billing \| 120 per minute \| \| upload \| `POST /media/upload-url` and `POST /seo/backlinks/import` \| 60 per minute \| \| pipeline \| `POST /pipeline/runs`, `POST /pipeline/articles/{id}/requeue`, `POST /delivery/cms/push` and the seven paid SEO scans \| 10 per minute \| \| auth \| `POST /auth/device` and `POST /auth/device/token`, per IP address \| 60 per minute \| `POST /comments` adds three limits, named in `error.limit` on its 429: `reader` (5 per reader in 10 minutes, by `reader_ip`), `site` (300 per Site per hour) and `queue` (2,000 awaiting review). Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
| 500 | - | `INTERNAL_ERROR`. Our fault. Quote the `request_id` from the body if you contact support. Safe to retry; send the same `Idempotency-Key` so a request that did succeed is not repeated. |
| 503 | - | `MAINTENANCE`. Writes are paused, platform wide or for your Site. Reads usually work and your published blog stays up. Retry after `Retry-After`. |

```bash
curl https://api.writavo.com/v1/analytics/setup \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"
```

### PATCH /analytics/settings

Turn analytics on or off, or change the extra domains

- **Operation id**: `updateAnalyticsSettings`
- **Scope**: `site:write`
- **Permission**: `website.settings`
- **Rate limit class**: write
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: no

Send `enabled`, `extra_domains`, or both. `extra_domains` replaces the whole list (up to 20)
and each one also counts its subdomains: add every domain the script runs on that is not
already the Site's primary domain, a verified custom domain or a reverse-proxy target (an app
on another domain, a staging host you want counted). A pasted URL is reduced to its host.
While `enabled` is false every visit is dropped. Returns the same shape as
`GET /analytics/setup`. Recorded in the audit log.

**Request body** (required)

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean | no | Count visits (true) or drop them all (false). |
| `extra_domains` | string[] | no | Replaces the whole list. Bare domains (`docs.example.com`); a pasted URL is reduced to its host. Each counts its subdomains too. `[]` clears the list. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | AnalyticsSetup | The setup after the change. |
| 400 | - | `INVALID_REQUEST`. Bad JSON, an unusable query parameter value, or a missing required header. |
| 401 | - | `INVALID_API_KEY`, `API_KEY_REVOKED` or `API_KEY_EXPIRED`: no key, or an unusable one. It never distinguishes "no such key" from "wrong key". |
| 403 | - | `INSUFFICIENT_SCOPE`. The key lacks this operation's scope, or its creator's permissions no longer cover it. Another Site's object is always 404, never this. A 403 may also be: - `AGENT_ACCESS_DISABLED` - AI agent access is turned off. - `APPROVAL_DENIED` - a person denied this action. - `FORBIDDEN` (organisation, team, settings) - a change no scope allows, such as an AI agent changing the access of the person it acts for, anything about ownership, or a setting only a person may change. The message says what to do instead. |
| 422 | - | `VALIDATION_FAILED`. The values are not acceptable; `error.fields` maps each field to a message. Common causes: publishing without a title, slug or content; scheduling in the past; sending `status` on a create or update. |
| 429 | - | `RATE_LIMIT_EXCEEDED`. Back off and honour `Retry-After`. Limits are per key, per minute, by endpoint class. The two device sign-in endpoints take no key, so they are limited per IP address. \| Class \| Endpoints \| Limit \| \|---\|---\|---\| \| read \| every GET \| 600 per minute \| \| write \| POST, PATCH and DELETE on content, taxonomy, keys, webhooks, the content plan, formats and prompts, settings, delivery, SEO curation, the team and billing \| 120 per minute \| \| upload \| `POST /media/upload-url` and `POST /seo/backlinks/import` \| 60 per minute \| \| pipeline \| `POST /pipeline/runs`, `POST /pipeline/articles/{id}/requeue`, `POST /delivery/cms/push` and the seven paid SEO scans \| 10 per minute \| \| auth \| `POST /auth/device` and `POST /auth/device/token`, per IP address \| 60 per minute \| `POST /comments` adds three limits, named in `error.limit` on its 429: `reader` (5 per reader in 10 minutes, by `reader_ip`), `site` (300 per Site per hour) and `queue` (2,000 awaiting review). Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
| 500 | - | `INTERNAL_ERROR`. Our fault. Quote the `request_id` from the body if you contact support. Safe to retry; send the same `Idempotency-Key` so a request that did succeed is not repeated. |
| 503 | - | `MAINTENANCE`. Writes are paused, platform wide or for your Site. Reads usually work and your published blog stays up. Retry after `Retry-After`. |

```bash
curl -X PATCH https://api.writavo.com/v1/analytics/settings \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
  "extra_domains": [
    "docs.example.com"
  ]
}'
```

### GET /analytics/visitors

Read the visitor report

- **Operation id**: `getVisitorAnalytics`
- **Scope**: `insights:read`
- **Permission**: `analytics.view`
- **Rate limit class**: read
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: no

Visitors, pageviews, bounces and engaged time for a range of UTC days, with the previous range
of the same length for comparison, one row per day (`daily`, every day of the range, zeros
included) and the top 50 values of each breakdown: pages, entry pages, sources, referrers, UTM
source, medium and campaign, country, region, city, device, browser and operating system.

Default range: the last 30 days (`to` today, `from` 29 days before). At most 400 days. Numbers
are rolled up from the raw events every 15 minutes, so a visit shows here up to 15 minutes
after it happens; `GET /analytics/setup` shows raw arrivals at once. A visitor is counted once
per day per Site from a daily-salted hash; no cookies are used.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | date | no | First UTC day, YYYY-MM-DD. Default 29 days before `to`. |
| `to` | query | date | no | Last UTC day, YYYY-MM-DD. Default today. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | VisitorAnalytics | The report. |
| 401 | - | `INVALID_API_KEY`, `API_KEY_REVOKED` or `API_KEY_EXPIRED`: no key, or an unusable one. It never distinguishes "no such key" from "wrong key". |
| 403 | - | `INSUFFICIENT_SCOPE`. The key lacks this operation's scope, or its creator's permissions no longer cover it. Another Site's object is always 404, never this. A 403 may also be: - `AGENT_ACCESS_DISABLED` - AI agent access is turned off. - `APPROVAL_DENIED` - a person denied this action. - `FORBIDDEN` (organisation, team, settings) - a change no scope allows, such as an AI agent changing the access of the person it acts for, anything about ownership, or a setting only a person may change. The message says what to do instead. |
| 422 | - | `VALIDATION_FAILED`. The values are not acceptable; `error.fields` maps each field to a message. Common causes: publishing without a title, slug or content; scheduling in the past; sending `status` on a create or update. |
| 429 | - | `RATE_LIMIT_EXCEEDED`. Back off and honour `Retry-After`. Limits are per key, per minute, by endpoint class. The two device sign-in endpoints take no key, so they are limited per IP address. \| Class \| Endpoints \| Limit \| \|---\|---\|---\| \| read \| every GET \| 600 per minute \| \| write \| POST, PATCH and DELETE on content, taxonomy, keys, webhooks, the content plan, formats and prompts, settings, delivery, SEO curation, the team and billing \| 120 per minute \| \| upload \| `POST /media/upload-url` and `POST /seo/backlinks/import` \| 60 per minute \| \| pipeline \| `POST /pipeline/runs`, `POST /pipeline/articles/{id}/requeue`, `POST /delivery/cms/push` and the seven paid SEO scans \| 10 per minute \| \| auth \| `POST /auth/device` and `POST /auth/device/token`, per IP address \| 60 per minute \| `POST /comments` adds three limits, named in `error.limit` on its 429: `reader` (5 per reader in 10 minutes, by `reader_ip`), `site` (300 per Site per hour) and `queue` (2,000 awaiting review). Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
| 500 | - | `INTERNAL_ERROR`. Our fault. Quote the `request_id` from the body if you contact support. Safe to retry; send the same `Idempotency-Key` so a request that did succeed is not repeated. |
| 503 | - | `MAINTENANCE`. Writes are paused, platform wide or for your Site. Reads usually work and your published blog stays up. Retry after `Retry-After`. |

```bash
curl https://api.writavo.com/v1/analytics/visitors \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"
```

### POST /analytics/install-check

Check that the analytics script is installed on a page

- **Operation id**: `checkAnalyticsInstall`
- **Scope**: `insights:read`
- **Permission**: `analytics.view`
- **Rate limit class**: write
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: no

Fetch one page the way a search engine would (server HTML, no JavaScript) and check, in this
order: `page_reachable` (it answers 2xx with HTML), `tag_present` (a script whose src ends in
`/api/a/s`), `site_id_matches` (its `data-site` is this Site's id, not another Site's),
`collector_public` (it loads over https from the public collector, not localhost),
`include_matches` (when the tag has `data-include`, the pattern is valid and matches this
page's path), `collecting_enabled` (collecting is on, and the host the page ends on counts)
and `recent_events` (an event arrived in the last 24 hours). Each check has a sentence saying
what to fix.

`status` is `failed` when the page will not be counted (`page_reachable`, `tag_present`,
`site_id_matches` or `collecting_enabled` failed), `warning` when anything else failed, and
`ok` otherwise. No events yet is only a warning: the script stays silent on localhost, 127.x
and file: pages and in automated browsers, so a fresh install needs one real visit in an
ordinary browser. A script added only in the browser after the page loads (a tag manager, a
lazy `next/script`) is not in the server HTML, so `tag_present` fails even though visits may
still arrive; `recent_events` and `GET /analytics/setup` show whether they do.

`url` defaults to the Site's first verified custom domain, else its primary domain. Its host
must be one this Site counts visits from (`allowed_domains` in `GET /analytics/setup`),
otherwise `422` on `url`: add the domain with `PATCH /analytics/settings` first. Free; one page
fetch of at most 2 MB, following up to three redirects.

**Request body**

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | null | no | The http(s) address of a page that should carry the script. Its host must be one this Site counts visits from. Omitted: the Site's first verified custom domain, else its primary domain. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | AnalyticsInstallCheck | The verdict, with every check. |
| 400 | - | `INVALID_REQUEST`. Bad JSON, an unusable query parameter value, or a missing required header. |
| 401 | - | `INVALID_API_KEY`, `API_KEY_REVOKED` or `API_KEY_EXPIRED`: no key, or an unusable one. It never distinguishes "no such key" from "wrong key". |
| 403 | - | `INSUFFICIENT_SCOPE`. The key lacks this operation's scope, or its creator's permissions no longer cover it. Another Site's object is always 404, never this. A 403 may also be: - `AGENT_ACCESS_DISABLED` - AI agent access is turned off. - `APPROVAL_DENIED` - a person denied this action. - `FORBIDDEN` (organisation, team, settings) - a change no scope allows, such as an AI agent changing the access of the person it acts for, anything about ownership, or a setting only a person may change. The message says what to do instead. |
| 422 | - | `VALIDATION_FAILED`. The values are not acceptable; `error.fields` maps each field to a message. Common causes: publishing without a title, slug or content; scheduling in the past; sending `status` on a create or update. |
| 429 | - | `RATE_LIMIT_EXCEEDED`. Back off and honour `Retry-After`. Limits are per key, per minute, by endpoint class. The two device sign-in endpoints take no key, so they are limited per IP address. \| Class \| Endpoints \| Limit \| \|---\|---\|---\| \| read \| every GET \| 600 per minute \| \| write \| POST, PATCH and DELETE on content, taxonomy, keys, webhooks, the content plan, formats and prompts, settings, delivery, SEO curation, the team and billing \| 120 per minute \| \| upload \| `POST /media/upload-url` and `POST /seo/backlinks/import` \| 60 per minute \| \| pipeline \| `POST /pipeline/runs`, `POST /pipeline/articles/{id}/requeue`, `POST /delivery/cms/push` and the seven paid SEO scans \| 10 per minute \| \| auth \| `POST /auth/device` and `POST /auth/device/token`, per IP address \| 60 per minute \| `POST /comments` adds three limits, named in `error.limit` on its 429: `reader` (5 per reader in 10 minutes, by `reader_ip`), `site` (300 per Site per hour) and `queue` (2,000 awaiting review). Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
| 500 | - | `INTERNAL_ERROR`. Our fault. Quote the `request_id` from the body if you contact support. Safe to retry; send the same `Idempotency-Key` so a request that did succeed is not repeated. |
| 503 | - | `MAINTENANCE`. Writes are paused, platform wide or for your Site. Reads usually work and your published blog stays up. Retry after `Retry-After`. |

```bash
curl -X POST https://api.writavo.com/v1/analytics/install-check \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/blog/how-to-choose-a-headless-cms"
}'
```
