Skip to content

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

NameTypeRequiredValues and limits
order_idstringYes
check_idstringNo

What it answers

Every answer has status and, where useful, message in plain words.

FieldMeaning
baselineThe 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.
currentThe latest check (or the check_id given): on of of.
lineOne point per check: check_id, date, on, of. Both numbers, because of moves as AI changes what it cites.
placementsEach page you logged: on_target (on_list, joined_later, not_on_list, own_site), phrases, AIs and cited_since.
linksCounts 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

statusWhat it means
invalid_inputorder_id isn't an order id. Take one from get_dashboard.
not_foundNo order with that id on this account.
invalid_inputcheck_id isn't a scheduled check of this order with a list of cited sites.
forbiddenThe 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 errorAn 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.

The call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_gap",
    "arguments": {
      "order_id": "00000000-0000-4000-8000-000000000002"
    }
  }
}
The answer (structured content)
{
  "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": "…"
}