---
title: SEO Reports and Site Scans
description: "RackHelm can produce AI-written SEO reports for a customer's hosted website: a scan of the live site, a short review step where the customer confirms their brand details, and then a generated report they can read in the portal or…"
url: "https://rackhelm.com/documentation/seo-reports/"
updated: "2026-09-24"
category: "Content, Storefront & Marketing"
---

# SEO Reports and Site Scans

RackHelm can produce AI-written SEO reports for a customer's hosted website: a scan of the live site, a short review step where the customer confirms their brand details, and then a generated report they can read in the portal or download as a PDF. Operators watch every scan from the admin area; customers run them from their own site. This article covers both.

## Before you start

> **Note:** Viewing scans in the admin area needs `view_seo_reports`; deleting one needs the separate `manage_seo_reports` permission, so a read-only role cannot remove records. Both are held by the built-in **Administrator** role.

SEO reporting is a licensed integration. Configure it under **Integrations → AI SEO Reporting**: switch **Enable AI SEO Feature** on and enter your **AI SEO License Key**. The SEO tab only appears on a customer's website dashboard when both are in place. The scan itself also needs the site to have a domain — a website service with no domain recorded returns "Domain not found for this site."

## Settings that control who may scan

| Field | What it does |
| --- | --- |
| **Enable AI SEO Feature** | Master switch for the integration. With it off, the SEO tab is not shown to customers. |
| **AI SEO License Key** | Authenticates you with the SEO service. Stored write-only — the field shows dots once a key is saved and stays blank on load; leave it blank to keep the current key. |
| **Default Paid Scans Allowed** | Allowance for customers who hold the AI SEO add-on. `-1` means unlimited — the shipped default. `0` means no scans at all. An individual add-on, or a selected add-on option, can override it. |
| **Default Paid Reset Period (Days)** | Rolling window for the paid allowance. `0` means the allowance is for the lifetime of the service. |
| **Enable Freemium Mode** | Lets customers who do not hold the AI SEO add-on run a limited number of scans. Off means only add-on holders may scan at all. |
| **Free Scans Allowed** | How many scans a non-add-on customer gets per site. Ships as 1. A role can override it. |
| **Reset Period (Days)** | Rolling window for the free allowance; `0` means lifetime. |
| **Allow Users to Delete Scans** | Lets customers remove their own scan records. Deleting a scan never resets the freemium counter, whatever this is set to. |
| **Freemium Paywall Message** | The wording shown when a customer runs out of free scans — up to 500 characters. |
| **Enable PDF Export** | Controls whether a completed report is also rendered as a downloadable PDF. |

> **Warning:** `0` and `-1` are not interchangeable. `-1` is the "unlimited" sentinel; `0` denies scanning entirely.

> **Warning:** Every switch on this screen reads as *off* until the form has been saved at least once, even where the wording suggests otherwise — an unsaved setting has no stored value and is treated as off. Open the screen, set each switch deliberately and save, rather than assuming a default.

## What the customer does

From their website's dashboard the customer opens the SEO section at `/sites/{site}/seo`:

1. **Start an analysis.** The scan is created and the site is submitted to the SEO service. Only one analysis per site can be in flight at a time.
2. **Review the brand details.** When the service reports back, the scan moves to a review step where the customer checks the brand information that was extracted from their site and picks a language.
3. **Generate the report.** That confirmation triggers the report itself.
4. **Read or download it.** When the report lands, it is viewable in the portal, and downloadable as a PDF if **Enable PDF Export** is on.

Scans and allowances belong to the *account*, not the individual login, so sub-accounts share the primary account's quota. Failed scans do not burn an allowance; deleted ones do.

## The admin view

Open **Reports → SEO Reports**. The screen shows counters for total, completed and pending/running scans plus the average run time, with filters for status and for a single customer.

![The admin SEO Reports list with summary cards, a status filter and a table of scans](/wp-content/uploads/rackhelm-docs/content-seo-reports-index.png)
Every scan on the system, with the customer, the website URL, when it was requested and how long it ran.

Select a row to read the stored report and the brand details captured for it. Deleting a scan from here is permanent from the operator's point of view and requires `manage_seo_reports`.

A per-customer view of the same data is available on the client record, under **Clients → (customer) → SEO Reports**.

## Scan states

| State | Meaning |
| --- | --- |
| Pending analysis | Submitted to the SEO service; waiting for it to call back. |
| Waiting user confirmation | The analysis returned. The customer must review the brand details before a report can be produced. |
| Generating report | Report generation has been requested and is running. |
| Completed | The report is stored and readable. |
| Failed | The service rejected the request or reported an error. Does not count against the allowance. |

Results arrive by webhook. Each callback URL is signed and expires 24 hours after it is issued, and the review step is issued a fresh signature of its own rather than reusing the first one.

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| "AI SEO is not enabled for this package" | Freemium is off and the customer does not hold the AI SEO add-on. |
| The customer sees the free-scan limit message | They have used their allowance for that site. Raise **Free Scans Allowed**, set a reset window, or sell them the add-on. |
| "Domain not found for this site" | The service has no domain recorded in its variables or provisioning metadata. Fix the service's domain first. |
| "An analysis is already in progress for this domain" | One scan per site at a time. Wait for it to complete or fail. |
| A scan sits at pending for a long time | The callback never arrived. Check that your portal URL is reachable from the internet and that the signed webhook has not passed its 24-hour window; the customer can start a fresh scan. |
| "Report is not ready yet" | The report is still generating, or the scan failed. Check the scan's status in the admin list. |
| "PDF is not available or still generating" | No PDF file is stored for that scan yet, or **Enable PDF Export** is off in the integration settings. |
| Setting the paid allowance to 0 gave unlimited scans | Older installs treated 0 as unlimited. Use `-1` for unlimited and `0` to deny. |
| A sub-account cannot get a fresh allowance | Correct — quotas are counted per account, not per login. |
| The **Pending/Running** counter and the **Pending** status filter always show nothing | They look for a scan whose status is literally `pending`, which is never written. In-flight scans are stored as `pending_analysis`, `waiting_user_confirmation` or `generating_report`. Read the **Status** column in the table instead. |