Updated: August 25, 2026

Home Assistant - Cloudflare Pages Build Usage#

1. Project Objective#

Add a simple Home Assistant sensor that shows how much of the Cloudflare Pages monthly build allowance has been used.

The sensor should answer:

How many of my 500 Cloudflare Pages builds have I used this month?

2. Project Scope#

The project will deliver one Home Assistant entity:

sensor.cloudflare_pages_builds

The sensor will show:

• builds used this month;
• builds remaining;
• percentage of the monthly allowance used;
• usage by Pages project;
• the current reporting month;
• the time of the last successful update;
• whether the information is current or unavailable.

This project does not include a dashboard, automation, custom integration, HACS component, or unrelated Home Assistant changes.

3. Pre-requisites#

• 3.1 Access to the active Home Assistant installation and its configuration files.
• 3.2 The Cloudflare account ID for the Pages projects to monitor.
• 3.3 A Cloudflare API credential with read-only Pages access.

4. Project Risks and Decisions#

• 4.1 Confirm the active Home Assistant host and configuration location.
• 4.2 Confirm the preferred Home Assistant secret-storage method.
• 4.3 Confirm the backup and configuration-validation process before changes are made.
• 4.4 Confirm whether a YAML reload or Home Assistant restart will be required.

5. Deliverables#

• 5.1 A working Cloudflare Pages usage sensor in Home Assistant.
• 5.2 Secure configuration for the Cloudflare account details and read-only API credential.
• 5.3 Reliable monthly usage totals covering all Pages projects.
• 5.4 Clear failure behavior when Cloudflare cannot be reached or returns invalid data.
• 5.5 A short operating note explaining how to test and verify the sensor.

6. Project Milestones#

Confirm the Integration Approach#

• 6.1 Inspect the existing Home Assistant setup.
• 6.2 Confirm where the new sensor and secure credentials should be configured.
• 6.3 Confirm that the change can be made without affecting unrelated Home Assistant features.

Build the Usage Counter#

• 6.4 Connect to Cloudflare using the supplied account ID and read-only API credential.
• 6.5 Collect the current month’s build usage across all Cloudflare Pages projects.
• 6.6 Ensure the result distinguishes actual builds from deployments that did not use a build.
• 6.7 Ensure the result remains correct when the account has many projects or deployments.

Add the Home Assistant Sensor#

• 6.8 Add the sensor with the friendly name Cloudflare Pages Builds.
• 6.9 Display the build count as the sensor state.
• 6.10 Add the remaining usage information as sensor attributes.
• 6.11 Set the update interval to approximately once every 30–60 minutes.

Secure and Validate the Result#

• 6.12 Keep the API credential out of source files, Git, logs, commands, and Home Assistant-visible sensor data.
• 6.13 Verify that authentication errors, Cloudflare outages, and invalid responses are clearly visible rather than appearing as zero usage.
• 6.14 Test the sensor manually and in Home Assistant.
• 6.15 Validate the Home Assistant configuration.
• 6.16 Record whether a reload or restart was required.

7. Completion Criteria#

• 7.1 The entity sensor.cloudflare_pages_builds is available in Home Assistant.
• 7.2 Its value matches the current month’s Cloudflare Pages build usage.
• 7.3 Usage is correctly aggregated across all Pages projects.
• 7.4 Non-build deployments are not incorrectly counted.
• 7.5 The monthly limit is represented as 500 builds.
• 7.6 The sensor clearly indicates when its data is unavailable or cannot be trusted.
• 7.7 Credentials remain protected.
• 7.8 No unrelated Home Assistant configuration has been changed.