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
| 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 |
|---|---|
check, checks | The check read, and every check of the order to choose from. |
ais | The 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_do | Scheduled checks: what to change, each with its evidence label. |
sources | The websites AI cited, with their label (claim it, get mentioned) and the competitors on each page. |
published | Pages you logged, and whether AI cited each since it was added. |
four_way | Each 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_ranges | Counts per AI and per mode; a range only at 40 or more answers. |
results_url | The page for this check. |
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. |
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_matrix",
"arguments": {
"order_id": "00000000-0000-4000-8000-000000000002"
}
}
}{
"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": "…"
}