get_pages_to_beat
Pages AI cited, per phrase.
For each phrase of one check (or one phrase), the pages the answers cited, most cited first: which AIs cited each, whether it is your own site, whether you and which competitors are on the page (null when we didn't read it), what the page has (words, FAQ, prices, reviews, structured data), and its label (Yours, Claim it, Get mentioned, Wrong about you). With the backlinks add-on: you_linked, whether that site links to yours (null where it wasn't asked). Without check_id: the latest scheduled check.
Who can use it
- Access
- A paid order. you_linked needs the backlinks add-on.
- Scope
scan:read- Changes anything
- No. Read-only.
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
order_id | string | Yes | |
phrase_id | string | No | |
check_id | string | No |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
check | The check read: check_id and date. |
phrases[] | phrase_id, phrase, yours_cited (how many of the pages are your own) and pages. |
pages[] | url, host, cited (answers in this check that cited it), ais, yours, kind, pill (Yours, Claim it, Get mentioned, Wrong about you), you_on_page and competitors_on_page (null where we didn't read the page), page_facts (title, words, faq, prices, reviews, structured_data), audience (an estimate of Google visits a month, when looked up). |
you_linked | With the backlinks add-on: whether that site links to yours; null where it wasn't asked. |
Errors
| status | What it means |
|---|---|
invalid_input | order_id isn't an order id. Take one from get_dashboard. |
not_found | No order with that id on this account. |
invalid_input | phrase_id isn't one of this order's phrases. |
forbidden | The credential lacks the tool's scope, or an agent's owner has no ScanFree account yet (the owner signs in on the website once). |
Input validation error | An argument doesn't match the schema below. The call fails with MCP error -32602, naming the field. |
Errors before the tool runs (a missing key, too many requests) are on the MCP page.
Example
Example shape; values are illustrative.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_pages_to_beat",
"arguments": {
"order_id": "00000000-0000-4000-8000-000000000002",
"phrase_id": "00000000-0000-4000-8000-000000000005"
}
}
}{
"status": "ok",
"order_id": "00000000-0000-4000-8000-000000000002",
"check": {
"check_id": "00000000-0000-4000-8000-000000000003",
"date": "2026-11-18"
},
"phrases": [
{
"phrase_id": "00000000-0000-4000-8000-000000000005",
"phrase": "emergency plumber boise",
"yours_cited": 0,
"pages": [
{
"url": "https://directory.example/boise/plumbers",
"host": "directory.example",
"cited": 3,
"ais": [
"ChatGPT",
"Perplexity"
],
"yours": false,
"kind": "directory",
"pill": "Claim it",
"audience": null,
"you_on_page": false,
"competitors_on_page": [
"Another Plumber Co"
],
"page_facts": {
"title": "…",
"words": 1200,
"faq": true,
"prices": false,
"reviews": true,
"structured_data": [
"ItemList"
]
}
}
]
}
],
"note": "…"
}