# How to Interpret OpenSEO Scan Results: Decoding the Site Audit JSON Payload

> Decode OpenSEO scan results with this guide. Understand your site audit JSON payload, including overall score, issue buckets, and detailed metrics from Lighthouse and Google Search Console.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-06

---

**OpenSEO scan results return a structured JSON payload containing an `overallScore`, per-page issue buckets (`errors`, `warnings`, `suggestions`), and detailed metrics from Lighthouse and Google Search Console that you can query via the MCP `runSiteAuditTool` endpoint.**

OpenSEO is an open-source technical SEO platform that crawls websites through a **Site Audit** workflow. When you initiate a scan, the system aggregates data from multiple sources and returns a comprehensive report. Understanding how to interpret open-seo scan results enables you to prioritize fixes based on severity and measure the impact of your optimizations.

## Architecture of the Site Audit System

The scan pipeline consists of several coordinated components defined in the `every-app/open-seo` repository:

- **[`SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/SiteAuditWorkflow.ts)** – Orchestrates the full audit pipeline from page discovery to final scoring. Located at [`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts).
- **[`site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/site-audit-tools.ts)** – Provides low-level data gathering helpers for Lighthouse and Google Search Console. Located at [`src/server/mcp/tools/site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/site-audit-tools.ts).
- **[`audit.schema.ts`](https://github.com/every-app/open-seo/blob/main/audit.schema.ts)** – Defines the TypeScript schema for the JSON report stored in the database. Located at [`src/db/audit.schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/audit.schema.ts).
- **[`server.ts`](https://github.com/every-app/open-seo/blob/main/server.ts)** – Registers the MCP endpoint `runSiteAuditTool` that exposes scan results to agents and the UI.
- **`_marketing/features/site-audit`** – React components that render the audit dashboard in the web interface at `web/src/routes/_marketing/features/site-audit`.

## Anatomy of the Scan Payload

The MCP endpoint and UI consume a consistent JSON structure. Here is the typical payload schema:

```json
{
  "url": "https://example.com",
  "overallScore": 78,
  "pages": [
    {
      "url": "https://example.com/",
      "score": 85,
      "issues": {
        "errors": ["Missing title tag", "Broken canonical"],
        "warnings": ["Missing meta description"],
        "suggestions": ["Add structured data"]
      },
      "metrics": {
        "lighthouse": { "performance": 90, "seo": 80 },
        "gsc": { "clicks": 1200, "impressions": 5000 }
      }
    }
  ],
  "summary": {
    "totalPages": 42,
    "errorCount": 7,
    "warningCount": 19,
    "suggestionCount": 34,
    "categoryBreakdown": {
      "performance": 80,
      "seo": 70,
      "accessibility": 90,
      "bestPractices": 75
    }
  },
  "createdAt": "2024-09-01T12:34:56Z"
}

```

Key fields to analyze:

- **`overallScore`** – Weighted composite from 0-100 indicating site health.
- **`pages`** – Array of individual URL results, each containing a `score` and `issues` object.
- **`issues`** – Categorized into three severity buckets:
  - **Errors**: Critical problems blocking indexing (e.g., missing `<title>`, blocked resources).
  - **Warnings**: Medium-priority issues degrading SEO (e.g., uncompressed images, duplicate tags).
  - **Suggestions**: Optional enhancements (e.g., internal linking improvements).
- **`metrics.lighthouse`**: Core Web Vitals and performance data.
- **`metrics.gsc`**: Real-world performance data from Google Search Console.
- **`summary.categoryBreakdown`**: Scores across Performance, SEO, Accessibility, and Best Practices.

## How to Prioritize Fixes from Scan Results

Follow this severity-based workflow when interpreting results:

1. **Review `overallScore` first.**
   - **Above 80**: Healthy site with minor optimizations needed.
   - **60-80**: Needs work; address warnings to prevent ranking drops.
   - **Below 60**: Critical issues requiring immediate intervention.

2. **Check `summary.errorCount`.**
   - Any errors present indicate crawlability or indexing blockers. Prioritize these above all else.

3. **Analyze high-traffic pages in the `pages` array.**
   - Focus on URLs with low individual scores that drag down the aggregate rating.

4. **Process issues in severity order:**
   - Fix **errors** immediately (missing title tags, broken canonicals).
   - Address **warnings** next (meta descriptions, image optimization).
   - Implement **suggestions** last (structured data, schema markup).

5. **Validate Core Web Vitals in `metrics.lighthouse`.**
   - LCP, FID, and CLS values directly impact Google rankings.

6. **Correlate with `metrics.gsc` data.**
   - Compare scan dates with impression/click trends to verify that technical fixes improve organic performance.

## Accessing Scan Results via the MCP Endpoint

Fetch audit data programmatically using the `runSiteAuditTool` endpoint registered in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts):

```typescript
import fetch from 'node-fetch';

const BASE = 'https://openseo.example.com/mcp';
const SITE = 'https://example.com';

async function getAudit() {
  const res = await fetch(
    `${BASE}/runSiteAuditTool?url=${encodeURIComponent(SITE)}`
  );
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const report = await res.json();

  console.log('Overall Score:', report.overallScore);
  console.log('Errors:', report.summary.errorCount);
  console.log('Top page score:', report.pages[0]?.score);
  
  return report;
}

getAudit().catch(console.error);

```

This handler wires directly to the `SiteAuditWorkflow` defined in [`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts).

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts) | Orchestrates the audit pipeline and aggregates results. |
| [`src/server/mcp/tools/site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/site-audit-tools.ts) | Low-level helpers for fetching Lighthouse and GSC data. |
| [`src/db/audit.schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/audit.schema.ts) | Database schema defining the JSON report structure. |
| [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) | MCP server exposing the `runSiteAuditTool` endpoint. |
| `web/src/routes/_marketing/features/site-audit` | Frontend components rendering scan results. |

## Summary

- OpenSEO scan results use a standardized JSON payload with **`overallScore`**, **`pages`**, and **`summary`** sections.
- Issues are bucketed into **`errors`** (critical), **`warnings`** (medium), and **`suggestions`** (low priority).
- Per-page metrics include **Lighthouse** scores for Core Web Vitals and **Google Search Console** performance data.
- Access results programmatically via the **`runSiteAuditTool`** MCP endpoint or through the React-based web UI.
- Reference [`SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/SiteAuditWorkflow.ts) and [`audit.schema.ts`](https://github.com/every-app/open-seo/blob/main/audit.schema.ts) to trace how specific fields are calculated and stored.

## Frequently Asked Questions

### What does the `overallScore` represent in OpenSEO?

The `overallScore` is a weighted composite value between 0 and 100 calculated by the `SiteAuditWorkflow`. It aggregates individual page scores and category metrics (Performance, SEO, Accessibility) to provide a single health indicator for the entire domain.

### How do errors differ from warnings in the scan results?

**Errors** indicate critical issues that prevent proper crawling or indexing, such as missing title tags or server errors. **Warnings** represent technical debt that degrades user experience and SEO performance but does not block indexing, such as missing meta descriptions or unoptimized images.

### Can I customize the audit schema to track additional metrics?

Yes. The JSON structure is defined in [`src/db/audit.schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/audit.schema.ts). You can extend this schema to include custom fields, but ensure you update the `SiteAuditWorkflow` to populate those fields during the aggregation phase to maintain data integrity.

### How do I access scan results without using the web interface?

You can query the **`runSiteAuditTool`** endpoint directly via the MCP server exposed in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts). This returns the raw JSON payload suitable for integration with CI/CD pipelines, Slack notifications, or external dashboards.