Scans

Each GroundScore scan produces an overall score, per-pillar sub-scores, and a detailed list of check results. List the most recent scans for a site, or read a single scan's full detail.

List scans for a site

GET/api/v1/sites/{siteId}/scansscope: read:scans

Returns the 50 most-recent scans for the given site, newest first. Each entry is a compact summary. Call the detail endpoint for the full breakdown.

Path parameters

Parameter	Type	Description
`siteId`	string	Site ID from GET /api/v1/sites.

Example request

bash

curl -H "Authorization: Bearer gs_live_yourkeyhere" \
     https://app.groundscore.ai/api/v1/sites/clx8h2k4p0001qz7m3n9d5f2g/scans

Example response

json

{
  "data": {
    "scans": [
      {
        "id": "clx9m4t7v0003qz7m8b2k6h1w",
        "score": 72,
        "status": "completed",
        "completedAt": "2026-05-22T03:15:00.000Z"
      }
    ]
  }
}

The list includes scans in every state, newest first. status is one of queued, processing, completed, or failed. score and completedAt are null until a scan completes, so filter on status before charting a score.

Get scan detail

GET/api/v1/sites/{siteId}/scans/{scanId}scope: read:scans

Returns the scan's overall score, its per-pillar sub-scores, and the first 20 individual check results.

Path parameters

Parameter	Type	Description
`siteId`	string	Site ID.
`scanId`	string	Scan ID from the list endpoint.

Example request

bash

curl -H "Authorization: Bearer gs_live_yourkeyhere" \
     https://app.groundscore.ai/api/v1/sites/clx8h2k4p0001qz7m3n9d5f2g/scans/clx9m4t7v0003qz7m8b2k6h1w

Example response

json

{
  "data": {
    "scan": {
      "id": "clx9m4t7v0003qz7m8b2k6h1w",
      "score": 72,
      "status": "completed",
      "completedAt": "2026-05-22T03:15:00.000Z",
      "pillarScores": [
        { "pillar": "authority",     "score": 65, "weight": 0.5 },
        { "pillar": "entity",        "score": 80, "weight": 0.35 },
        { "pillar": "ai_visibility", "score": 68, "weight": 0.15 }
      ],
      "checkResults": [
        {
          "name": "Organization schema",
          "category": "meta",
          "status": "warn",
          "value": null,
          "description": "Found Organization schema but no LocalBusiness.",
          "durationMs": 42
        }
        /* …up to 20 entries */
      ]
    }
  }
}

Each entry in checkResults carries a name, a category (one of dns, http, meta, robots, sitemap, security), a status (pass, warn, fail, or error), a free-form value, a human-readable description, and the durationMs the check took.

Why only 20 check results? Full scans contain dozens of low-level checks. We return the first 20 in the order the scan recorded them (internal checks first, then external provider checks) so responses stay small. They are not ranked by impact, so do not read the order as a priority list. The internal crawlSignals payload is omitted entirely. It's pipeline state, not API data.

Pillar keys

A completed scan returns exactly three pillars. The pillar key is the stored identifier, which does not always match the name the pillar carries in the GroundScore dashboard. weight is that pillar's contribution to the overall score.

Key	Shown in-app as	Weight	Meaning
`authority`	Authority & Trust	0.5	Trust signals: citations earned, domain authority, off-site mentions.
`entity`	Site Readiness	0.35	Structured data, identity, crawlability, brand grounding.
`ai_visibility`	AI Presence	0.15	How well AI engines surface and cite this site.

Errors

Code	When
`not_found`	Site or scan does not exist, or the scan belongs to a different site.
`insufficient_scope`	Key lacks read:scans.