Metrics
Plenary keeps a small set of numbers for the console dashboard: content and media counts, daily delivery traffic, editing activity, upcoming scheduled publishes, and monthly usage. They are basic operational figures, not a site analytics product. Read them on the Dashboard, or call the endpoints below.
All endpoints are read-only and live under /api/v1. Every metrics endpoint requires the admin:metrics:read capability on the site it reports, which each site’s Admin role has by default; /usage is for super users only. Because API keys cannot hold admin:* capabilities, call these endpoints with a user’s access token.
Plenary exposes no Prometheus or other scrape endpoint. For uptime checks, use GET /api/v1/health.
How traffic is counted
Section titled “How traffic is counted”Plenary counts delivery traffic: requests authenticated with an API key, public or private. Requests from the console use a user session and are never counted, so browsing the console does not inflate the numbers.
| Counter | Counts |
|---|---|
content_read |
Entry reads through GET /api/v1/content/{model_key} and GET /api/v1/content/{model_key}/{slug_or_uuid} |
form_submit |
Accepted form entries |
form_spam |
Form entries classified as spam |
media_read |
Media detail reads through GET /api/v1/media/{media_id} |
api_request |
Every request authenticated with an API key, on any route |
Counts are kept in memory and written every 30 seconds into daily totals per site and model. A server crash loses at most 30 seconds of counts. Daily totals are kept for 400 days.
Two limits to know:
- Media file downloads (
/media/{media_id}/{filename}) are not counted, because the front proxy usually serves those files directly. media_readhas no site, so filtering bysite_keyleaves it out. It appears only in the all-sites view.
GET /metrics/overview
Section titled “GET /metrics/overview”Content-side counts for the dashboard tiles.
| Query parameter | Meaning |
|---|---|
site_key |
Optional. Limits entry counts and entries_created_7d to one site. |
curl "https://your-instance.plenarycms.io/api/v1/metrics/overview?site_key=marketing" \ -H "Authorization: Bearer $PLENARY_ACCESS_TOKEN"{ "models": [ { "id": "b351d1eb-2635-472a-bdfc-781ef262ecfe", "key": "blog_post", "name": "Blog Post", "kind": "collection", "entry_count": 42 } ], "forms": [ { "id": "75292dcf-44ec-4577-930f-4e366fffe08e", "key": "contact", "name": "Contact", "status_counts": { "new": 3, "read": 9, "spam": 1 } } ], "media_count": 120, "media_bytes": 2147483648, "users_count": 6, "roles_count": 4, "active_webhooks": 2, "webhooks_last_delivery_at": "2026-09-19T01:55:07.469Z", "entries_created_7d": 41}| Field | Meaning |
|---|---|
models |
Collection and singleton models with their entry counts. |
forms |
Forms with a count of entries per triage status. new is what the dashboard shows as needing triage. |
media_count, media_bytes |
Number and total size of media assets. Not site-specific. |
users_count, roles_count |
Users and roles on the instance. |
active_webhooks |
Active webhooks. |
webhooks_last_delivery_at |
Time of the most recent webhook delivery, or null if none. |
entries_created_7d |
Content entries (not form entries) created in the last 7 days. |
GET /metrics/traffic
Section titled “GET /metrics/traffic”Daily delivery traffic. Every day in the range is present, with zeros where nothing was counted.
| Query parameter | Meaning |
|---|---|
from |
First day, inclusive, as YYYY-MM-DD in UTC. |
to |
Last day, inclusive, as YYYY-MM-DD in UTC. |
site_key |
Optional. One site only. |
Without from and to, the range is the last 30 days. The maximum range is 400 days.
curl "https://your-instance.plenarycms.io/api/v1/metrics/traffic?from=2026-10-05&to=2026-10-06" \ -H "Authorization: Bearer $PLENARY_ACCESS_TOKEN"{ "from": "2026-10-05", "to": "2026-10-06", "days": [ { "day": "2026-10-05", "content_read": 0, "form_submit": 0, "form_spam": 0, "media_read": 0, "api_request": 0 }, { "day": "2026-10-06", "content_read": 8, "form_submit": 0, "form_spam": 0, "media_read": 0, "api_request": 8 } ]}| Error (HTTP 400) | Cause |
|---|---|
metrics_date_invalid |
from or to is not a YYYY-MM-DD date. |
metrics_range_invalid |
from is after to. |
metrics_range_too_large |
The range is longer than 400 days. |
GET /metrics/activity
Section titled “GET /metrics/activity”Editing activity, read from revision history. Only content entry revisions count; form entries do not create revisions.
| Query parameter | Meaning |
|---|---|
days |
Window length in days, ending today. Default 126 (18 weeks). Maximum 400. |
site_key |
Optional. One site only. |
{ "from": "2026-06-04", "to": "2026-10-07", "days": [ { "day": "2026-06-04", "revisions": 3 } ], "models": [ { "id": "e2868186-6a1a-4a0f-a6d0-25c8c7b61e33", "key": "blog_post", "name": "Blog Post", "count": 86 } ], "week": { "revisions": 12, "publishes": 4, "models_changed": 3 }}| Field | Meaning |
|---|---|
days |
Revisions per day across the window, with zeros where there were none. |
models |
The 10 most-edited models in the window. A deleted model keeps its id and count with an empty key and name. |
week |
The last 7 days, whatever the window: revisions, publishes, and the number of distinct models changed. With site_key, models_changed counts only that site’s models. |
| Error (HTTP 400) | Cause |
|---|---|
metrics_range_invalid |
days is not a positive integer. |
metrics_range_too_large |
days is more than 400. |
GET /metrics/scheduled
Section titled “GET /metrics/scheduled”Upcoming scheduled publishes and unpublishes, soonest first, at most 20 items.
| Query parameter | Meaning |
|---|---|
days |
Window length in days, starting now. Default 7. Maximum 90. |
site_key |
Optional. One site only. |
{ "items": [ { "entry_id": "131156b3-48b4-448e-b2d0-1799e5943b3a", "model_id": "86a0e2be-a692-4b75-9505-d7f3572357a5", "model_key": "page", "model_name": "Page", "site_key": "marketing", "title": "Autumn Campaign Launch", "action": "publish", "at": "2026-10-09T09:00:00Z" } ]}action is publish or unpublish. title is the entry’s title field, then its slug, then empty. An entry with both a publish and an unpublish in the window appears twice. Errors are the same as /metrics/activity.
GET /usage
Section titled “GET /usage”What this instance has used this calendar month (UTC), as shown on Plenary Cloud’s Subscription page. Available on self-hosted instances too. Requires a super user.
{ "period_start": "2026-10-01T00:00:00Z", "resets_at": "2026-11-01T00:00:00Z", "seats": 14, "sites": 3, "storage_bytes": 6871947673, "api_requests": 1903311, "form_entries": 4120}| Field | Meaning |
|---|---|
seats |
Active users. |
sites |
Sites. |
storage_bytes |
Total media storage. |
api_requests |
API-key requests this month (the sum of daily api_request counts). Can lag by up to 30 seconds. |
form_entries |
Form entries created this month. |
Health check
Section titled “Health check”GET /api/v1/health needs no authentication. Use it for load balancer and uptime checks.
{ "status": "ok", "database": "ok", "version": "1.0.0", "edition": "on-prem", "license": "ok" }It returns 200 while the database answers, and 503 with "status": "degraded" and "database": "error" when it does not. license reports the license state on self-hosted instances (ok, expired, missing, and so on) but never changes the HTTP status. On Plenary Cloud there is no license field. See Licensing.
Related
Section titled “Related”- Permissions: granting
admin:metrics:readto a custom role. - API Keys: the keys whose requests are counted.