---
title: "GrowthWebMonitor Documentation"
description: "Technical documentation for GrowthWebMonitor — a self-hosted uptime, performance and image-weight monitor for the websites your agency manages. This page covers how the plugin works, setup, the shortc..."
url: https://growthplugins.com/docs/growthwebmonitor/
date: 2026-11-17
modified: 2026-11-17
author: "GrowthPlugins"
type: page
lang: en
---

# GrowthWebMonitor Documentation

*Technical documentation for **GrowthWebMonitor** — a self-hosted uptime, performance and image-weight monitor for the websites your agency manages. This page covers how the [plugin](https://growthplugins.com/) works, setup, the shortcode, checks and alerts, settings, data model, REST API, and the AI / MCP abilities layer.*

**Version:** 1.0.0  |  **Requires:** WordPress with WP-Cron enabled; Abilities API (WordPress 6.9+) for the AI layer  |  **Text domain:** `growthwebmonitor`

## 1. Overview — how it works

GrowthWebMonitor turns one WordPress installation into a monitoring hub for many sites. Each monitored site is stored as a private custom post (`gp_website`), and three scheduled jobs check them in the background:

- **Uptime ping** — an HTTP request to each site. The ping is the source of truth for the UP/DOWN status.
- **Performance** — Google PageSpeed Insights scores for desktop and mobile.
- **Heavy images** — scans the images on each site’s page and records any that exceed your size limit or return an HTTP error.

It is **single-tenant**: all sites belong to the installation, settings are global, and one API token connects external integrations. The plugin exposes three interfaces on top of the same data:

- **Front-end dashboard** — the `[growthwebmonitor]` shortcode (dashboard + site [management](https://growthplugins.com/plugin/growthprojects/)).
- **REST API** — the `growthwebmonitor/v1` namespace, authenticated with a global token.
- **AI abilities** — WordPress Abilities API tools, optionally exposed over MCP.

## 2. Installation & setup

1. Upload and activate the plugin. On activation it creates three tables (see [section 7](#data-model)), stores default settings and schedules the background jobs.
2. Go to **GrowthWebMonitor → Settings** in wp-admin and enter your **Google PageSpeed API key**. Without it, performance checks are skipped (pings and image scans still run).
3. Review alert recipients, thresholds and check frequencies ([section 5](#settings)).
4. Create a page with the `[growthwebmonitor]` shortcode — or use the button in Settings that creates the dashboard page for you.
5. Add your sites from the dashboard’s *Sites* tab (or from the *GrowthWebMonitor* menu in wp-admin).

**Tip:** WP-Cron only runs when the site receives traffic. For reliable minute-level checks on a low-traffic install, disable WP-Cron’s page-load trigger and call `wp-cron.php` from a real server cron job.

## 3. Shortcode

```
[growthwebmonitor]
```

Renders the monitoring app with two tabs:

- **Dashboard** — aggregated metrics and a table of every site with its current status, scores and last check.
- **Sites** — add, edit and delete monitored sites.

Clicking a site opens an inline detail panel with performance charts over time, failed pings grouped by day, and the list of heavy images. From there you can run *Ping now* or a *Full check* (PageSpeed + ping + images) on demand.

**Access:** the shortcode only renders for users with the `manage_options` capability; everyone else sees a “no permission” notice. To give non-admin staff access, grant `manage_options` to their role with a role-editor plugin.

Charts are rendered with ApexCharts, loaded from the jsDelivr CDN.

## 4. Checks & alerts

| Check | Cron hook | Default frequency | What it does | Alert |
| --- | --- | --- | --- | --- |
| Uptime ping | `gp_cron_hourly` | Hourly | HTTP GET to each site (30 s timeout). `200` and `403` count as UP; anything else, including timeouts, counts as a failure. Only failures are stored, to keep the table small. | Email when a site accumulates **3 consecutive failures**. |
| Performance | `gp_cron_daily` | Daily | Runs PageSpeed Insights v5 for desktop and mobile (retrying once on failure) and stores both scores. | Email listing sites whose desktop or mobile score falls below its threshold. |
| Heavy images | `gp_cron_daily_images` | Daily | Fetches the site’s page, collects every `<img src>`, and checks each file’s size. | No email; results appear in the site detail panel, the API and the abilities. |

Frequencies are configurable per check:

- **Ping:** every 15 min, 30 min, hour, 6 hours, twice daily, or daily.
- **Performance:** hourly, every 6 hours, twice daily, daily, or weekly.
- **Images:** daily, weekly, or monthly.

Changing a frequency reschedules the job automatically. Deactivating the plugin unschedules all three jobs.

## 5. Settings

All settings live in **GrowthWebMonitor → Settings** (requires `manage_options`) and are stored as WordPress options:

| Setting | Option | Default |
| --- | --- | --- |
| Google PageSpeed API key | `gp_pagespeed_api_key` | (empty) |
| Alert email recipients | `gp_alert_emails` | Site admin email |
| Email notifications on/off | `gp_notifications_enabled` | On |
| Desktop score threshold (0–100) | `gp_threshold_desktop` | 75 |
| Mobile score threshold (0–100) | `gp_threshold_mobile` | 75 |
| Max image size (KB) | `gp_max_image_size_kb` | 512 |
| Ping / PageSpeed / image frequency | `gp_freq_ping`, `gp_freq_pagespeed`, `gp_freq_images` | hourly / daily / daily |

The Settings screen is also where you generate or revoke the API token ([section 6](#rest-api)). To run checks immediately instead of waiting for the schedule, use *Ping now* / *Full check* in a site’s detail panel, or the `check-all-sites` ability ([section 8](#abilities)).

## 6. REST API

**Namespace:** `growthwebmonitor/v1`  —  base URL `/wp-json/growthwebmonitor/v1`.

**Authentication:** a single global token, generated in Settings. Only a SHA-256 hash is stored, so copy the token when it is shown. Send it in any of these ways:

- `Authorization: Bearer ` header (recommended)
- `X-API-Token: ` header
- `?token=` query parameter

Missing or invalid tokens return `401`. All endpoints are read-only (`GET`).

| Route | Description |
| --- | --- |
| `/sites` | All sites with their current status and last check. |
| `/sites/performance?num=10` | Latest *N* PageSpeed logs for every site. |
| `/sites/{id}/performance?num=30` | PageSpeed logs for one site. |
| `/sites/ping` | Live ping to every site (status, HTTP code, response time in ms). |
| `/sites/{id}/ping` | Live ping to one site. |
| `/sites/getpings?days=7` | Failed-ping history for every site (last 30 entries if `days` is omitted). |
| `/sites/{id}/getpings?days=7` | Failed-ping history for one site. |

### Example

```
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://example.com/wp-json/growthwebmonitor/v1/sites
```

Typical uses: a status page, a Slack bot, or a central agency dashboard that aggregates several installs.

## 7. Data model

Each site is a `gp_website` post (private, not publicly queryable). Its URL and latest results are post meta: `url`, `status` (UP/DOWN), `last_check`, `performance_desktop`, `performance_mobile`.

History is stored in three custom tables (with the site’s table prefix):

| Table | Columns | Notes |
| --- | --- | --- |
| `{prefix}gp_logs` | id, time, website_id, status, performance_desktop, performance_mobile | One row per PageSpeed run. |
| `{prefix}gp_pings` | id, time, website_id, status | Failed pings only (HTTP code, or `400` for connection errors). |
| `{prefix}gp_large_images` | id, time, website_id, image_url, image_size, status_code | Images over the size limit or returning an error. |

## 8. AI abilities & MCP

GrowthWebMonitor registers **15 abilities** on the **WordPress Abilities API** (WordPress 6.9+), in three categories. On older WordPress versions this layer is simply skipped.

| Ability | Category | Type |
| --- | --- | --- |
| `growthwebmonitor/get-sites` | Sites | read-only |
| `growthwebmonitor/get-site` | Sites | read-only |
| `growthwebmonitor/add-site` | Sites | write |
| `growthwebmonitor/update-site` | Sites | idempotent |
| `growthwebmonitor/delete-site` | Sites | destructive |
| `growthwebmonitor/ping-site` | Checks | write (live ping, updates status) |
| `growthwebmonitor/check-site` | Checks | write (PageSpeed + ping + images; up to ~60 s) |
| `growthwebmonitor/check-all-sites` | Checks | write (full check on every site; slow) |
| `growthwebmonitor/get-dashboard-summary` | Diagnostics | read-only |
| `growthwebmonitor/get-sites-down` | Diagnostics | read-only |
| `growthwebmonitor/get-sites-below-threshold` | Diagnostics | read-only |
| `growthwebmonitor/get-sites-with-heavy-images` | Diagnostics | read-only |
| `growthwebmonitor/get-site-performance` | Diagnostics | read-only |
| `growthwebmonitor/get-site-pings` | Diagnostics | read-only |
| `growthwebmonitor/get-site-images` | Diagnostics | read-only |

Each ability declares a JSON input/output schema, so an assistant can safely handle requests such as “which client sites are down right now?” or “list sites with a mobile score under 50”.

### Permissions & MCP visibility

- Every ability requires `manage_options` by default.
- Non-destructive abilities are *MCP-public* by default. `delete-site` is destructive, so it is **not** exposed over MCP unless you opt in.
- The required capability and MCP visibility of each ability (or a whole category) can be overridden from the plugin’s Abilities settings, stored in the `gwm_abilities_config` option. Per-ability overrides take precedence over category defaults, which take precedence over the code defaults.

## 9. FAQ & troubleshooting

#### Performance scores stay at 0.

Check that a Google PageSpeed API key is saved in Settings. Without a key the performance check is skipped. The PageSpeed API can also time out on very slow sites; the plugin retries once per run.

#### Checks don’t run on schedule.

WP-Cron needs traffic to fire. On quiet installs, trigger `wp-cron.php` from a server cron job, or run a site’s check on demand from its detail panel.

#### Why does a 403 count as UP?

Many sites behind a firewall or bot protection return `403` to automated requests while working normally for visitors. Treating it as UP avoids false “site down” alerts.

#### Can non-admin staff use the dashboard?

The shortcode, settings and abilities require `manage_options`. Grant that capability to the staff role, or change the ability capabilities in the Abilities settings.

#### The REST API returns 401.

Generate a token in Settings and send it as a Bearer token. If the token was revoked or regenerated, update your integration with the new one.

---

**Back to** [GrowthWebMonitor product page](https://growthplugins.com/plugin/growthwebmonitor/).
