---
title: "Engagement"
description: "Per-article views, reactions, share clicks and comment counts.  Record from your server (`POST /engagement/events`), read one or up to 50 (`GET /engagement/posts/{slug}`, `GET /engagement/posts?slugs=`), or import a migrated blog's history (`POST /engagement/import`). Site-wide report: `GET /seo/engagement`."
canonical: "https://writavo.com/docs/api/engagement"
last-updated: "2026-09-30"
---

# Engagement

Per-article views, reactions, share clicks and comment counts.

Record from your server (`POST /engagement/events`), read one or up to 50
(`GET /engagement/posts/{slug}`, `GET /engagement/posts?slugs=`), or import a migrated blog's
history (`POST /engagement/import`). Site-wide report: `GET /seo/engagement`.

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

### POST /engagement/events

Record a view, reaction or share

- **Operation id**: `recordEngagement`
- **Scope**: `engagement:write`
- **Permission**: `articles.write`
- **Rate limit class**: write
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: no

For a site that renders its articles itself: record one view, a reader's reaction, or a share
click on a published article, from your own server (never from the browser: the key is a
secret key). Filter bots and link prefetches before calling.

Reactions follow one rule per reader and article: a reader has at most one current reaction;
sending another replaces it and `reaction: null` removes it. `visitor_id` is your own stable
anonymous id for the reader (a cookie value, for example); Writavo stores only a hash of it.
The response is the article's totals after the write. An unknown or unpublished slug is 404.
A recorded view, reaction or share shows in the dashboard and in `GET /seo/engagement` at once.

This records article views. Visitors and pageviews come from the visitor analytics script
instead: one script tag on the pages that show your articles. `GET /analytics/setup` returns
it ready to paste (guide: https://writavo.com/docs/analytics). Until it is added, visitors
are shown as not measured.

**Request body** (required)

| Field | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | The published article's slug. |
| `type` | string | yes |  |
| `reaction` | string | null | no | Required when type is reaction. null removes the reader's reaction. |
| `platform` | string | no | Required when type is share. `other` is a copied link or the system share sheet. |
| `visitor_id` | string | null | no | Your stable anonymous id for the reader. Required for reactions; only a hash is stored. With it, a view or a share counts once per 30 minutes per reader and article. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 201 | PostEngagement | Recorded. The article's totals after the write. |
| 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. |
| 404 | - | `NOT_FOUND`. No such object, or it belongs to another Site. **The two are deliberately indistinguishable and never return 403.** If the id is right, check you are using the right Site's key. |
| 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/engagement/events \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "<slug>",
  "type": "view"
}'
```

### POST /engagement/import

Import engagement history

- **Operation id**: `importEngagement`
- **Scope**: `engagement:write`
- **Permission**: `articles.write`
- **Rate limit class**: write
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: no

Bring a blog's engagement history to Writavo when it migrates: views, reactions and share
clicks per article per day, and each reader's current reaction. Articles are matched by
`external_id` or `slug` on this Site, in any status. Call it from a server with a secret key.

**SET, never add.** A `daily` row replaces that article's counts for that day: each field
you send (`views`, `reactions`, `shares`) replaces that field, a field you leave out keeps
its stored value (0 on a new day), and `shares` replaces all four platforms (a platform you
do not name becomes 0). A `reactions` row replaces that reader's current reaction on that
article. Sending the same payload twice changes nothing, so a retried or repeated import can
never double-count.

**Which days.** Any UTC day from 1990-01-01 up to today, including days that already have
live counts: the import replaces them. Today is for the day you cut over: the import sets
the day's counts as they stood on the old system, and views and shares Writavo records
after the import add to them. Sending today's row again sets it again, so send it once.
`set_at` on a reaction may be any past instant.

**Reactions.** Writavo keeps a per-day reaction TOTAL and, separately, one current reaction
per reader (which is what the per-type counts are made of). A `daily` row's `reactions` may
be a number or per-type counts, which are summed. An imported reader's reaction replaces a
live one and moves the day totals like a live change does (one off the day the old reaction
was made, one onto the day of `set_at`). Daily rows are applied after reactions, so a day
whose total you send explicitly ends at exactly that number.

**Dry run first.** `dry_run` defaults to true: every row is checked and matched, `posts`
and `problems` are reported, and nothing is written. Send `dry_run: false` to write. A row
with a problem is skipped and listed in `problems`; the valid rows are still written.

Imported rows are marked as imported internally and count everywhere exactly like live
engagement: the public counters, the dashboard and `GET /seo/engagement`. `visitor_id` is
hashed with the Site's id before it is stored, the same way `POST /engagement/events` does,
so a reader keeps their imported reaction when they come back. Each applied import is
recorded in the audit log with its counts.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string | yes | A unique key per logical operation, 1 to 255 printable ASCII characters (a UUID works), scoped to the Site and endpoint and kept for 24 hours. - Same key and body: the original response is replayed, so retrying a timeout is safe. - Same key, different body: `409 IDEMPOTENCY_KEY_CONFLICT`. - Same key while the first is running: `409 IDEMPOTENCY_KEY_IN_FLIGHT`; wait and retry. |

**Request body** (required)

| Field | Type | Required | Description |
|---|---|---|---|
| `dry_run` | boolean | no | Check and report without writing. Defaults to true; send false to write. |
| `daily` | EngagementImportDay[] | no | Per article per UTC day, views, the reaction total and shares per platform. |
| `reactions` | EngagementImportPick[] | no | Each reader's current reaction per article. One row per reader and article. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | EngagementImportResult | The report. With `dry_run` it describes what would be written. |
| 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. |
| 409 | - | The request collides with the current state. Read `code`: - `SLUG_CONFLICT` - the slug is taken. - `IDEMPOTENCY_KEY_CONFLICT` / `IDEMPOTENCY_KEY_IN_FLIGHT` - key reused with another body, or still running. - `CONFLICT` - the object changed under you. Re-read and retry. - `APPROVAL_INVALID` - the `Writavo-Approval` is expired, used, unknown, for another request, or its effect changed. Retry without it for a new approval. - `PREREQUISITE_MISSING` / `FEATURE_UNAVAILABLE` (settings, delivery, SEO) - something is not set up (the message names what sets it up), or Writavo has it switched off (the message names the free alternative). Nothing was done or charged. |
| 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/engagement/import \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "daily": [
    {
      "external_id": "blog:1",
      "day": "2026-05-10",
      "views": 120,
      "reactions": {
        "useful": 2,
        "insightful": 1
      },
      "shares": {
        "x": 1,
        "linkedin": 3
      }
    },
    {
      "slug": "how-to-choose-a-headless-cms",
      "day": "2026-05-11",
      "views": 87
    }
  ],
  "reactions": [
    {
      "external_id": "blog:1",
      "visitor_id": "anon_7f3a9c",
      "reaction": "useful",
      "set_at": "2026-05-10T14:03:00Z"
    }
  ]
}'
```

### GET /engagement/posts/{slug}

Read an article's views, reactions and shares

- **Operation id**: `getPostEngagement`
- **Scope**: `articles:read`
- **Permission**: `none`
- **Rate limit class**: read
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: yes

The public counters for one published article: lifetime views, the six reaction totals, share
clicks per platform, approved comments and, with `visitor_id`, that reader's current reaction.
Safe for a publishable key: these numbers are shown on the page anyway. For several articles
at once, use `GET /engagement/posts?slugs=`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The article's slug. |
| `visitor_id` | query | string | no | Your anonymous id for the reader, to return their current reaction. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | PostEngagement | The article's counters. |
| 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. |
| 404 | - | `NOT_FOUND`. No such object, or it belongs to another Site. **The two are deliberately indistinguishable and never return 403.** If the id is right, check you are using the right Site's key. |
| 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/engagement/posts/3f1b0c7a-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"
```

### GET /engagement/posts

Read views, reactions, shares and comment counts for several articles

- **Operation id**: `listPostsEngagement`
- **Scope**: `articles:read`
- **Permission**: `none`
- **Rate limit class**: read
- **Plan feature**: `none`
- **Spends credits**: no
- **Publishable key may call it**: yes

The public counters of up to 50 published articles in one call, for an index or archive page:
the same numbers as `GET /engagement/posts/{slug}` for each. Slugs that are unknown or not
published are listed in `missing` rather than failing the request, so one unpublished post
never breaks a page. `posts` and `missing` keep the order the slugs were asked in (a slug
asked twice appears once, at its first position). Safe for a publishable key.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slugs` | query | string | yes | Comma separated slugs, 1 to 50 after duplicates are removed, each up to 200 characters (`slugs=first-post,second-post`). More than 50 is `422` on `slugs`. |

**Responses**

| Status | Data | Description |
|---|---|---|
| 200 | PostEngagementBatch | The counters of every published article named, and the slugs that are not. |
| 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/engagement/posts \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"
```
