Skip to content

get_matrix

Results of one check.

Phrases x AIs for one check of an order: in how many of the 2 runs the business was named, its best position, which businesses were named instead, and where the site ranks on Google (top 30) and Bing (top 20) for each phrase. Without check_id it returns the latest scheduled check.

Who can use it

Access
A paid order.
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
check, checksThe check read, and every check of the order to choose from.
aisThe AIs asked: key, label, mode (live search or training data).
phrases[]Each phrase: state, kind, named_instead, cells per AI (named_runs of answered_runs, best_position, could_not_run), google_rank and bing_rank (a position, or "not in the top N"), why_not_named when no live answer named the business.
one_thing, what_to_doScheduled checks: what to change, each with its evidence label.
sourcesThe websites AI cited, with their label (claim it, get mentioned) and the competitors on each page.
publishedPages you logged, and whether AI cited each since it was added.
four_wayEach live-search answer in one of four boxes (named_cited, named_not_cited, cited_not_named, neither), with answers as the total, no_links (answers with no links at all, inside named_not_cited or neither) and the same per AI in by_ai, counted phrases only; training_data apart as named of answers (no links, so never cited); labels gives the four in words. Counts, never added across the two kinds of answer.
totals, likely_rangesCounts per AI and per mode; a range only at 40 or more answers.
results_urlThe page for this check.

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.
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_matrix",
    "arguments": {
      "order_id": "00000000-0000-4000-8000-000000000002"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "order_id": "00000000-0000-4000-8000-000000000002",
  "check": {
    "check_id": "00000000-0000-4000-8000-000000000003",
    "date": "2026-11-18",
    "kind": "scheduled",
    "status": "complete"
  },
  "checks": [
    {
      "check_id": "00000000-0000-4000-8000-000000000003",
      "date": "2026-11-18",
      "kind": "scheduled"
    }
  ],
  "ais": [
    {
      "key": "perplexity.live.fast",
      "label": "Perplexity",
      "mode": "live_search"
    }
  ],
  "phrases": [
    {
      "phrase": "emergency plumber boise",
      "state": "active",
      "kind": "generic",
      "named_instead": [
        "Another Plumber Co"
      ],
      "google_rank": 7,
      "bing_rank": "not in the top 20",
      "ranks_checked": "2026-11-18",
      "cells": {
        "perplexity.live.fast": {
          "named_runs": 1,
          "answered_runs": 2,
          "best_position": 3,
          "could_not_run": 0
        }
      }
    }
  ],
  "totals": {
    "perplexity.live.fast": {
      "named": 1,
      "answered": 2
    }
  },
  "likely_ranges": {},
  "unconfirmed_names_left_out": 0,
  "results_url": "https://app.scanfree.dev/app/orders/00000000-0000-4000-8000-000000000002?check=00000000-0000-4000-8000-000000000003",
  "note": "…"
}