get_gap
Did the work close the gap?.
For one paid order: the baseline (the sites AI cited for its phrases at the first scheduled check, or at the check before the first logged page went live, dated, with the gap sites where competitors appear and you don't, each with now_on once a later check has you named in answers citing it or on its cited page), the current check, the line per check ({check_id, date, on, of}: you're on X of Y sites AI cited; both numbers, Y moves as AI changes what it cites), and each page you logged with published_pages: on_target (on_list, joined_later, not_on_list, own_site; about our list, not the page's worth), the phrases and AIs, and cited_since (counted from live_on). With check_id: the line up to that check. links (the backlinks add-on, or competitor research's link data; null without either): counts first with the date and "a backlink index" as the source, how many of the sites AI cited link to you and to each competitor, change_line (new and lost since the last run), one list with two marks (ai_cited; links_to_you, links_to), your top referring domains marked when AI also cites them, and the directories (links, lost, or no link to you found, never "not listed"; listed: a Google search of that site for your name). Read-only; counts only, never a verdict or a cause; never say links get a business named by AI.
Who can use it
- Access
- A paid order. links needs the backlinks add-on or competitor research.
- Scope
scan:read- Changes anything
- No. Read-only.
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
order_id | string | Yes | |
check_id | string | No |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
baseline | The dated list of sites AI cited at the start: on of of, and gap_sites (where competitors appear and you don't), each with now_on once a later check has you there. |
current | The latest check (or the check_id given): on of of. |
line | One point per check: check_id, date, on, of. Both numbers, because of moves as AI changes what it cites. |
placements | Each page you logged: on_target (on_list, joined_later, not_on_list, own_site), phrases, AIs and cited_since. |
links | Counts first with the date and "a backlink index" as the source: which cited sites link to you and to each competitor, what changed, and the directories. null without the add-on. |
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 | check_id isn't a scheduled check of this order with a list of cited sites. |
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_gap",
"arguments": {
"order_id": "00000000-0000-4000-8000-000000000002"
}
}
}{
"status": "ok",
"order_id": "00000000-0000-4000-8000-000000000002",
"baseline": {
"check_id": "00000000-0000-4000-8000-000000000008",
"date": "2026-10-18",
"on": 2,
"of": 14,
"competitors_on": 9,
"gaps": 6,
"line": "…",
"gap_sites": [
{
"site": "directory.example",
"kind": "directory",
"label": "Claim it",
"cited": 3,
"phrases": [
"…"
],
"ais": [
"ChatGPT"
],
"competitors": [
"Another Plumber Co"
],
"now_on": null
}
]
},
"current": {
"check_id": "00000000-0000-4000-8000-000000000003",
"date": "2026-11-18",
"on": 3,
"of": 15,
"competitors_on": 9,
"gaps": 5,
"line": "…"
},
"line": [
{
"check_id": "00000000-0000-4000-8000-000000000008",
"date": "2026-10-18",
"on": 2,
"of": 14
},
{
"check_id": "00000000-0000-4000-8000-000000000003",
"date": "2026-11-18",
"on": 3,
"of": 15
}
],
"placements": [],
"links": null,
"note": "…"
}