# Health Scores

https://api-docs.lumar.io/docs/graphql/health-scores

Health scores provide a single numeric summary (0--100) of your site's performance within a report category such as SEO, Accessibility, or Site Speed. They are calculated after every crawl based on the pass/fail results of individual health score tests.

## Querying a single health score

Use the `getHealthScore` query when you need the score for a specific report category and crawl. You can optionally scope the result to a segment.

```graphql
query GetHealthScore($input: GetHealthScoreInput!) {
  getHealthScore(input: $input) {
    crawlId
    healthScore
    categoryWeight
    createdAt
    healthScoreTestResults(first: 10) {
      nodes {
        reportCategoryCode
        passed
        severity
      }
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ",
    "reportCategoryCode": "seo"
  }
}
```

**Response:**
```json
{
  "data": {
    "getHealthScore": {
      "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ",
      "healthScore": 85.4,
      "categoryWeight": 1.0,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "healthScoreTestResults": {
        "nodes": [
          {
            "reportCategoryCode": "seo",
            "passed": true,
          }
        ]
      }
    }
  }
}
```

## Querying multiple health scores for a crawl

To retrieve scores for several categories at once, use the `healthScores` field on a `Crawl` object.

```graphql
query GetCrawlHealthScores($crawlId: ObjectID!) {
  getCrawl(id: $crawlId) {
    healthScores(reportCategoryCodes: ["seo", "accessibility", "site_speed"]) {
      healthScore
      reportCategoryCode
      categoryWeight
    }
  }
}
```

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

**Response:**
```json
{
  "data": {
    "getCrawl": {
      "healthScores": [
        {
          "healthScore": 85.4,
          "reportCategoryCode": "seo",
          "categoryWeight": 1.0
        },
        {
          "healthScore": 92.1,
          "reportCategoryCode": "accessibility",
          "categoryWeight": 1.0
        },
        {
          "healthScore": 78.3,
          "reportCategoryCode": "site_speed",
          "categoryWeight": 1.0
        }
      ]
    }
  }
}
```

## Health score trends

The `getHealthScoreTrendForCrawl` query returns historical health scores across multiple crawls, allowing you to chart improvements or regressions over time.

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

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

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

## Creating health score tests

Health score tests define the thresholds that determine whether a report category passes or fails. Use the `createHealthScoreTest` mutation to add a new test to a test suite.

```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"
      }
    }
  }
}
```

Key fields in `CreateHealthScoreTestInput`:

| Field                       | Description                                                                      |
| --------------------------- | -------------------------------------------------------------------------------- |
| `reportCategoryCode`        | The report category this test targets (e.g., `"seo"`).                           |
| `absoluteThreshold`         | The absolute number threshold for pass/fail.                                     |
| `relativeThreshold`         | Percentage change threshold (used when `thresholdType` is `Relative`).           |
| `thresholdType`             | Either `Relative` or `Absolute`.                                                 |
| `severity`                  | `Fail` or `Warning` -- controls how a breach is reported.                        |
| `automaticThresholdEnabled` | When `true`, Lumar adjusts thresholds automatically based on historical results. |

## Automatic thresholds

When `automaticThresholdEnabled` is set to `true`, Lumar will adjust the test threshold based on previous crawl results. You can control the acceptance behaviour for improving and worsening results independently using:

- `automaticThresholdAcceptanceWhenTestResultIsBetter` -- whether to automatically accept the new threshold when scores improve.
- `automaticThresholdAcceptanceWhenTestResultIsWorse` -- whether to automatically accept the new threshold when scores regress.

## Copying tests between projects

Use `copyHealthScoreTests` to duplicate health score tests from one project to another. Existing tests with the same `reportCategoryCode` in the target project will be overwritten.

```graphql
mutation CopyHealthScoreTests($input: CopyHealthScoreTestsInput!) {
  copyHealthScoreTests(input: $input) {
    healthScoreTests {
      reportCategoryCode
      absoluteThreshold
      severity
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "fromProjectId": "TjAwN1Byb2plY3Q2MTMy",
    "toProjectId": "TjAwN1Byb2plY3Q5OTA2",
    "reportCategoryCodes": ["seo", "accessibility"]
  }
}
```

**Response:**
```json
{
  "data": {
    "copyHealthScoreTests": {
      "healthScoreTests": [
        {
          "reportCategoryCode": "seo",
          "absoluteThreshold": 0.8,
          "severity": "Fail"
        },
        {
          "reportCategoryCode": "accessibility",
          "absoluteThreshold": 0.9,
          "severity": "Warning"
        }
      ]
    }
  }
}
```