Tutorial: Track SEO Health Over Time
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:
query GetOverallHealth($crawlId: ObjectID!) {
getCrawl(id: $crawlId) {
id
status
healthScores(reportCategoryCodes: ["seo"]) {
healthScore
reportCategoryCode
}
}
}
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:
query GetHealthTrend($crawlId: ObjectID!) {
getHealthScoreTrendForCrawl(crawlId: $crawlId, first: 5) {
nodes {
crawlId
healthScores {
healthScore
reportCategoryCode
}
}
totalCount
}
}
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):
mutation CreateCrawlUrlSegment($input: CreateCrawlUrlSegmentInput!) {
createCrawlUrlSegment(input: $input) {
segment {
id
name
group
crawlUrlFilter
createdAt
}
}
}
Then query the health score for that segment:
query GetSegmentHealth($crawlId: ObjectID!, $segmentId: ObjectID!) {
getCrawl(id: $crawlId) {
healthScore(reportCategoryCode: "seo", segmentId: $segmentId) {
healthScore
reportCategoryCode
segmentId
}
}
}
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:
mutation CreateHealthScoreTest($input: CreateHealthScoreTestInput!) {
createHealthScoreTest(input: $input) {
healthScoreTest {
absoluteThreshold
automaticThresholdEnabled
reportCategoryCode
severity
thresholdPredicate
thresholdType
}
}
}
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:
- Create a build schedule to run Protect builds on a regular cadence (see Setup Automated Monitoring).
- Configure webhooks to receive alerts when health score tests fail (see Webhooks).
- 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 -- full reference for health score queries and tests.
- Segments guide -- managing URL segments for granular monitoring.
- Report Templates Overview -- understand which reports contribute to health scores.