Skip to content

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.

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_read has no site, so filtering by site_key leaves it out. It appears only in the all-sites view.

Content-side counts for the dashboard tiles.

Query parameter Meaning
site_key Optional. Limits entry counts and entries_created_7d to one site.
Terminal window
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.

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.

Terminal window
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.

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.

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.

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.

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.

  • Permissions: granting admin:metrics:read to a custom role.
  • API Keys: the keys whose requests are counted.