# Tutorial: Track SEO Health Over Time

https://api-docs.lumar.io/docs/graphql/tutorials/track-seo-health

This tutorial shows how to use health scores, trends, segments, and tests to monitor your site's SEO performance over time.

## Step 1: Get the current health score

After a crawl finishes, query the overall SEO health score:

```graphql
query GetOverallHealth($crawlId: ObjectID!) {
  getCrawl(id: $crawlId) {
    id
    status
    healthScores(reportCategoryCodes: ["seo"]) {
      healthScore
      reportCategoryCode
    }
  }
}
```

**Variables:**
```json
{
  "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ"
}
```

**Response:**
```json
{
  "data": {
    "getCrawl": {
      "id": "TjAwNUNyYXdsMTU4MzI0NQ",
      "status": "Finished",
      "healthScores": [
        {
          "healthScore": 85.4,
          "reportCategoryCode": "seo"
        }
      ]
    }
  }
}
```

The health score is a value from 0 to 100, calculated from the pass/fail results of all health score tests in the `seo` report category.

## Step 2: View health score trends

Track how your health score changes across crawls to identify improvements or regressions:

```graphql
query GetHealthTrend($crawlId: ObjectID!) {
  getHealthScoreTrendForCrawl(crawlId: $crawlId, first: 5) {
    nodes {
      crawlId
      healthScores {
        healthScore
        reportCategoryCode
      }
    }
    totalCount
  }
}
```

**Variables:**
```json
{
  "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ"
}
```

**Response:**
```json
{
  "data": {
    "getHealthScoreTrendForCrawl": {
      "nodes": [
        {
          "crawlId": "TjAwNUNyYXdsMTU4MzI0Mw",
          "healthScores": [
            {
              "healthScore": 80.1,
              "reportCategoryCode": "seo"
            }
          ]
        },
        {
          "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ",
          "healthScores": [
            {
              "healthScore": 85.4,
              "reportCategoryCode": "seo"
            }
          ]
        }
      ],
      "totalCount": 2
    }
  }
}
```

This returns historical health scores ordered by crawl, allowing you to chart the trend over time.

## Step 3: Monitor segment health

Segments let you track health scores for specific sections of your site. For example, monitor your blog pages separately from product pages.

First, create a segment (if you do not have one):

```graphql
mutation CreateCrawlUrlSegment($input: CreateCrawlUrlSegmentInput!) {
  createCrawlUrlSegment(input: $input) {
    segment {
      id
      name
      group
      crawlUrlFilter
      createdAt
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "projectId": "TjAwN1Byb2plY3Q2MTMy",
    "name": "Blog Pages",
    "group": "Content",
    "crawlUrlFilter": { "url": { "contains": "/blog/" } }
  }
}
```

**Response:**
```json
{
  "data": {
    "createCrawlUrlSegment": {
      "segment": {
        "id": "TjAyMVNlZ21lbnQx",
        "name": "Blog Pages",
        "group": "Content",
        "crawlUrlFilter": { "url": { "contains": "/blog/" } },
        "createdAt": "2025-01-15T10:00:00.000Z"
      }
    }
  }
}
```

Then query the health score for that segment:

```graphql
query GetSegmentHealth($crawlId: ObjectID!, $segmentId: ObjectID!) {
  getCrawl(id: $crawlId) {
    healthScore(reportCategoryCode: "seo", segmentId: $segmentId) {
      healthScore
      reportCategoryCode
      segmentId
    }
  }
}
```

**Variables:**
```json
{
  "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ",
  "segmentId": "TjAyMVNlZ21lbnQx"
}
```

**Response:**
```json
{
  "data": {
    "getCrawl": {
      "healthScore": [
        {
          "healthScore": 88.2,
          "reportCategoryCode": "seo",
          "segmentId": "TjAyMVNlZ21lbnQx"
        }
      ]
    }
  }
}
```

## Step 4: Set up health score tests

Health score tests define the thresholds that determine whether your health score is acceptable. Create tests to enforce minimum standards:

```graphql
mutation CreateHealthScoreTest($input: CreateHealthScoreTestInput!) {
  createHealthScoreTest(input: $input) {
    healthScoreTest {
      absoluteThreshold
      automaticThresholdEnabled
      reportCategoryCode
      severity
      thresholdPredicate
      thresholdType
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "testSuiteId": "TjAxMVRlc3RTdWl0ZTEyMw",
    "reportCategoryCode": "seo",
    "absoluteThreshold": 0.8,
    "thresholdType": "Relative",
    "relativeThreshold": 10,
    "severity": "Fail",
    "automaticThresholdEnabled": false
  }
}
```

**Response:**
```json
{
  "data": {
    "createHealthScoreTest": {
      "healthScoreTest": {
        "absoluteThreshold": 0.8,
        "automaticThresholdEnabled": false,
        "reportCategoryCode": "seo",
        "severity": "Fail",
        "thresholdPredicate": "GreaterThanOrEqual",
        "thresholdType": "Relative"
      }
    }
  }
}
```

When a health score test fails, it will be flagged in build results and can trigger webhook notifications.

## Step 5: Automate with builds and alerts

To track health automatically:

1. **Create a build schedule** to run Protect builds on a regular cadence (see [Setup Automated Monitoring](setup-automated-monitoring)).
2. **Configure webhooks** to receive alerts when health score tests fail (see [Webhooks](../webhooks.md)).
3. **Query test results** after each build to see which tests passed and which failed.

## Interpreting health scores

| Score Range | Interpretation                                   |
| ----------- | ------------------------------------------------ |
| 90--100     | Excellent. Site meets or exceeds best practices. |
| 70--89      | Good. Some areas for improvement.                |
| 50--69      | Needs attention. Significant issues present.     |
| Below 50    | Critical. Major issues affecting site health.    |

## Next steps

- [Health Scores guide](../health-scores.md) -- full reference for health score queries and tests.
- [Segments guide](../segments.md) -- managing URL segments for granular monitoring.
- [Report Templates Overview](../report-templates-overview.md) -- understand which reports contribute to health scores.