Skip to content

check_status

A check in progress.

For one paid order: the check running now with how many answers are in (poll this, about once a minute; no call waits), the last finished check and when the next one is due.

Who can use it

Access
A paid order.
Scope
scan:read
Changes anything
No. Read-only.

Inputs

NameTypeRequiredValues and limits
order_idstringYes

What it answers

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

FieldMeaning
order_stateThe order's state.
in_progressThe check running now: check_id, kind, started_at, answers_in of answers_planned, and retrying_at when some answers will be tried again. null when none runs.
last_finishedThe last finished check: check_id, kind, status, finished_at.
next_check_atWhen the next check is due, or null.
messageWhat to do next. Poll about once a minute; no call waits.

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": "check_status",
    "arguments": {
      "order_id": "00000000-0000-4000-8000-000000000002"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "order_id": "00000000-0000-4000-8000-000000000002",
  "order_state": "active",
  "in_progress": {
    "check_id": "00000000-0000-4000-8000-000000000003",
    "kind": "scheduled",
    "started_at": "2026-11-21T09:00:00.000Z",
    "answers_in": 36,
    "answers_planned": 80
  },
  "last_finished": {
    "check_id": "00000000-0000-4000-8000-000000000008",
    "kind": "scheduled",
    "status": "complete",
    "finished_at": "2026-10-21T09:40:00.000Z"
  },
  "next_check_at": null,
  "message": "A check is running: 36 of 80 answers are in. Call check_status again in about a minute."
}