Publish Metrics API

Enterprise plans

This API provides programmatic access to usage metrics for your Builder Publish (CMS) content, available exclusively on Enterprise plans.

What to know

Generate a Private Key in your Organization Settings to access metrics data.
Metrics are returned at the Organization level, aggregated across all Publish and hybrid Spaces in the Organization, plus a per-Space breakdown.
Metrics are calculated once per day rather than updated instantly. Pageview and bandwidth numbers you see today reflect yesterday's activity.

Private API Keys

A Private API Key is a server-side credential that grants write access to your Builder Space. Use Private Keys when you need to:

Write or update content in your Builder Space programmatically
Fetch content that should remain private and not be publicly accessible

Only users with Admin permissions can view or create Private Keys.

Tip: Keep your Private API Key secret. Anyone with a Private Key has write access to your Builder content. Only use it in API calls from your server, not calls from public client applications.

Manage Private API Keys

To manage the Private Keys for your Space:

Go to your Space Settings.
To the right of Private Keys, click the Edit button.
Create or revoke as many keys as you need.

For more information on how to use Private Keys with models, visit Create a Private Model.

In rare situations, you may need to create a Private Key for your Organization. Follow the same process, but on your Organization's Settings page. For more details on this page, visit Manage your Organization.

Get Metrics

Metrics summarize Publish-side usage across your Organization over a period of time. The endpoint returns both an org-level aggregate and a per-Space breakdown in a single response.

Get Organization-level Publish metrics

Retrieves Publish usage data for an entire Organization. Only Spaces used for production Publish content are counted. Pure Fusion Spaces and staging/environment Spaces (clones of a production Space, used for testing content changes before going live) are excluded from the totals so they don't double-count against your real content activity.

Include your Organization's Private Key within the Authorization header. Query parameters:

Parameter	Required?	Description
`startDate`	Yes	Date in `YYYY-MM-DD` format (inclusive)
`endDate`	Yes	Date in `YYYY-MM-DD` format (inclusive)

Constraints:

endDate must be on or after startDate.
The date range must be no longer than 90 days.

Endpoint: https://builder.io/api/v1/orgs/publish/metrics

Example request:

curl -G https://builder.io/api/v1/orgs/publish/metrics \ -d startDate=2026-07-01 \ -d endDate=2026-07-31 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response:

{ "aggregated": { "entriesCreated": [ { "date": "2026-07-01", "count": 12 }, { "date": "2026-07-02", "count": 8 } ], "entriesTotal": 20, "pageViews": [ { "date": "2026-07-01", "count": 45231 }, { "date": "2026-07-02", "count": 47908 } ], "pageViewsTotal": 93139, "bandwidth": [ { "date": "2026-07-01", "GB": 3.42 }, { "date": "2026-07-02", "GB": 3.61 } ], "bandwidthTotal": 7.03, "testsLiveCount": 4 }, "bySpace": { "entriesCreated": { "abc123spaceid": 15, "def456spaceid": 5 }, "pageViews": { "abc123spaceid": 68204, "def456spaceid": 24935 }, "bandwidth": { "abc123spaceid": 5.11, "def456spaceid": 1.92 }, "lastActivity": { "abc123spaceid": "2026-07-30", "def456spaceid": "2026-07-14" } } }

If the Organization has no Publish or hybrid Spaces, the response returns empty arrays and zeroed counters rather than an error.

API Response Keys

Each API response is split into two top-level objects: aggregated (org-wide totals and daily series) and bySpace (per-Space breakdowns).

Aggregated fields

These fields appear in the aggregated object and cover every Publish/hybrid Space in the Organization.

Key	Description
`entriesCreated`	Array of `{ date, count }` — number of new content entries created per day within the requested range
`entriesTotal`	Sum of `entriesCreated.count` across the range
`pageViews`	Array of `{ date, count }` — total pageviews per day served across the org's Publish content
`pageViewsTotal`	Sum of `pageViews.count` across the range
`bandwidth`	Array of `{ date, GB }` — bandwidth in gigabytes served per day
`bandwidthTotal`	Sum of `bandwidth.count` across the range
`testsLiveCount`	Snapshot count of published content entries currently running an A/B test,`testRatio` between 0 and 1, at the time the endpoint is called

Per-Space fields

These fields appear in the bySpace object. Each key is a Space's Public API Key; each value is that Space's contribution over the requested range.

Key	Description
`entriesCreated`	Object mapping Space ID → count of entries created in that Space during the range
`pageViews`	Object mapping Space ID → total pageviews served for that Space during the range
`bandwidth`	Object mapping Space ID → gigabytes served for that Space during the range
`lastActivity`	Object mapping Space ID → most recent content-modification date in YYYY-MM-DD format. Not scoped to the requested range — reflects the all-time latest activity

Notes on data sources

Pageviews and bandwidth are aggregated nightly. Data for the previous day becomes available after ~04:30 UTC each day.
Entries created is queried live against the content store, so recent creations are reflected immediately.
Tests live is a live count of currently-live A/B tests, not a time-windowed metric. It is not affected by startDate / endDate.
Last activity per Space is cached for 60 seconds.

Possible errors

Status	Description
`400`	`startDate` or `endDate` is missing, not in Y`YYY-MM-DD` format, out of order, or the range exceeds 90 days
`401`	Object mapping Space ID → total pageviews served for that Space during the range
`404`	Object mapping Space ID → gigabytes served for that Space during the range
`500`	Object mapping Space ID → most recent content-modification date in YYYY-MM-DD format. Not scoped to the requested range — reflects the all-time latest activity

What's next

Review your Organization's Publish adoption by Viewing Insights inside the Builder app.
Combine these metrics with the Fusion Metrics API to get a full picture of usage across both products.

Was this article helpful?