Start and read WordPress scans
Start a WP PerformanceShield scan on a site through the API, wait for it to finish and read the score, findings and vulnerabilities.
This guide shows how to start a WordPress security scan on one site with the API, wait for it and read the result. It uses the same operations as the panel.
What you need
Section titled “What you need”- An API key with the scope
wpscan:readto read results andwpscan:writeto start a scan (scopes). The key never does more than its user: a reseller or client reaches only the sites of their own accounts. - The site id. List the sites of an account with
GET /api/v1/accounts/{account_id}/sitesand take theidof the WordPress site. - A server whose agent can scan. If it cannot, the summary says
"supported": falseand starting a scan answers409 wpscan_unsupported_agent.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"
1. Start a scan
Section titled “1. Start a scan”POST /api/v1/sites/{id}/wpscan/scans queues a scan and answers 202 at once; the scan runs later on the
server. The body is optional: mode is full (the default: integrity checks plus the malware checks over
every file) or integrity (the lighter daily check).
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan/scans" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"mode": "full"}'
{
"queued": true,
"scan": {
"id": "7c7c7c7c-1111-4222-8333-444455556666",
"site_id": "6b6b6b6b-1111-4222-8333-444455556666",
"mode": "full",
"reason": "on_demand",
"state": "queued",
"requested_at": "2026-11-14T10:02:11Z"
}
}
Keep scan.id:
export SCAN_ID="7c7c7c7c-1111-4222-8333-444455556666"
Only one scan runs at a time on a server, so a queued scan can wait for its turn. Send an
Idempotency-Key so a retry does not queue a second scan.
2. Wait for it to finish
Section titled “2. Wait for it to finish”GET /api/v1/wpscan/scans/{id} returns the scan and, once it has finished, its report. The scan moves through
queued, delivering and running to an end state: complete, partial (finished with a partial result), failed or cancelled. Poll every few seconds, or every minute for a large site.
until state=$(curl -fsS "$PLUSPANEL_URL/api/v1/wpscan/scans/$SCAN_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" | jq -r .scan.state) \
&& case "$state" in complete|partial|failed|cancelled) true ;; *) false ;; esac; do
sleep 10
done
echo "$state"
The fields worth knowing in scan:
score(0–100) andgrade(AtoF), set when the scan ends;nulland empty before that.findings_totalandvulnerabilities_total: what the scan found.started_atandfinished_at.erroranderror_codewhen the state isfailed.
The scan history of a site is GET /api/v1/sites/{id}/wpscan/scans (newest first; limit and before, the
requested_at of the last scan you got, page through it).
3. Read the summary
Section titled “3. Read the summary”GET /api/v1/sites/{id}/wpscan is the current picture of the site: the score is computed over the items that
are open now, so it changes when you fix or ignore something.
curl -fsS "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" \
| jq '{scored, score, grade, scanned_at, open_findings, open_vulnerabilities, running: .running.state}'
{
"scored": true,
"score": 82,
"grade": "B",
"scanned_at": "2026-11-14T10:04:40Z",
"open_findings": { "high": 1, "low": 2 },
"open_vulnerabilities": { "critical": 1 },
"running": null
}
scoredisfalseandscoreisnulluntil a scan has completely finished.open_findingsandopen_vulnerabilitiescount the open items by severity (info,low,medium,high,critical).last_scanis the latest finished scan,runningthe one queued or in flight, if any.quarantinedandquarantined_bytesdescribe the site’s quarantine;settingsholds the three automatic-fix switches.feed.attributionand theattributionof the vulnerabilities answer carry notices that you must show next to the vulnerability records if you display them in your own tool.
4. Read the findings and vulnerabilities
Section titled “4. Read the findings and vulnerabilities”GET /api/v1/sites/{id}/wpscan/findings lists what the scan found in the site’s files and database, most
severe first. Filters: state (open, resolved, quarantined, ignored), category and severity (the
minimum severity).
curl -fsS -G "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan/findings" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" \
--data-urlencode "state=open" --data-urlencode "severity=medium" \
| jq '.items[] | {id, severity, category, path, component}'
A finding has an id, a severity, a category, the path of the file, the component it belongs to (kind
core, plugin or theme, with slug and version), a state and two flags, quarantinable and
reinstallable, that say which fixes apply.
GET /api/v1/sites/{id}/wpscan/vulnerabilities lists the known vulnerabilities of the installed core, plugins
and themes, with title, severity, cvss, cve, installed_version, fixed_in and state (open,
fixed, ignored). It takes the filter state.
The same group of operations also fixes things: update a component, quarantine or reinstall files, ignore an
item and change the automatic-fix settings. These need wpscan:write; see the
API reference under wpscan.
Errors
Section titled “Errors”| Status | Code | Meaning |
|---|---|---|
401 |
invalid_api_key |
The key is missing, expired or revoked. |
403 |
The key has no wpscan scope, or the user may not use the site. |
|
404 |
The site or scan does not exist or is not visible to you. | |
409 |
edition_limit_reached |
Free edition: one on-demand scan per site per UTC day. The answer’s limit is wpscan_on_demand_daily. |
429 |
wpscan_rate_limited |
Pro and Enterprise: one on-demand scan per site every 10 minutes. Retry-After says when to try again. |
409 |
wpscan_unsupported_agent |
The server’s agent does not support scanning. |
Errors are problem details: branch on code.
Events
Section titled “Events”No webhook event is sent when a scan finishes: poll the scan as in step 2. Alerts that your alert rules raise
are sent as alert.firing and alert.resolved (event list).
Related
Section titled “Related”- WordPress security scanning: what is checked, when scans run and how fixes work.
- API reference: every
wpscanoperation, with its fields. - API conventions: errors, pagination, idempotency and ETags.
- Authentication & API keys: scopes and key handling.