# Report Templates Overview

https://api-docs.lumar.io/docs/graphql/report-templates-overview

Report templates define the reports available in Lumar. Each template specifies a filter on crawl data and belongs to one or more report categories. Understanding the data model is essential for querying the right data.

## Data model

A **Report Template** has:

- `code` -- a unique identifier (e.g., `"broken_pages"`, `"all_pages"`).
- `name` -- a human-readable label.
- `datasourceCodeEnum` -- the underlying datasource the report draws from.
- `reportCategories` -- the categories this report belongs to (e.g., SEO, Accessibility).
- `contributesToHealthScores` -- whether this report affects health score calculations.

## Datasource types

The `DatasourceCode` enum identifies the underlying data table for a report. Common datasources include:

| Datasource                         | Description                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
| `CrawlUrls`                        | Individual page-level data (URLs, status codes, titles, etc.). Most reports use this datasource. |
| `CrawlLinks`                       | Link-level data (source URL, target URL, anchor text, etc.).                                     |
| `CrawlSitemaps`                    | Sitemap data discovered during the crawl.                                                        |
| `CrawlHreflangs`                   | Hreflang tag data for internationalisation reports.                                              |
| `CrawlAccessibilityIssues`         | Accessibility audit issues aggregated by rule.                                                   |
| `CrawlAccessibilityIssueInstances` | Individual accessibility issue instances on specific elements.                                   |
| `CrawlSiteSpeedAudits`             | Lighthouse audit results.                                                                        |
| `CrawlSearchQueries`               | Google Search Console query data.                                                                |
| `CrawlUncrawledUrls`               | URLs discovered but not crawled.                                                                 |
| `CrawlDuplicateUrls`               | Groups of duplicate pages.                                                                       |
| `CrawlLinkedDomains`               | External domains linked from the crawled site.                                                   |

## Discovering available templates

Use the `getReportTemplates` query to browse the full catalogue of report templates. You can filter by datasource code or report category.

```graphql
query DiscoverReportTemplates {
  getReportTemplates(first: 5) {
    nodes {
      code
      name
      description
      datasourceCodeEnum
      contributesToHealthScores
      reportCategories {
        code
        name
      }
    }
    totalCount
  }
}
```

**Response:**
```json
{
  "data": {
    "getReportTemplates": {
      "nodes": [
        {
          "code": "all_pages",
          "name": "All Pages",
          "description": "All pages found during the crawl.",
          "datasourceCodeEnum": "CrawlUrls",
          "contributesToHealthScores": false,
          "reportCategories": [
            {
              "code": "seo",
              "name": "SEO"
            }
          ]
        },
        {
          "code": "broken_pages",
          "name": "Broken Pages",
          "description": "Pages returning a 4xx or 5xx HTTP status code.",
          "datasourceCodeEnum": "CrawlUrls",
          "contributesToHealthScores": true,
          "reportCategories": [
            {
              "code": "seo",
              "name": "SEO"
            }
          ]
        }
      ],
      "totalCount": 250
    }
  }
}
```

## Querying report data

Once you know the report template code, use `getReportStat` to fetch aggregated data and the underlying URLs for a specific crawl.

```graphql
query GetReportData($crawlId: ObjectID!) {
  getReportStat(
    input: { crawlId: $crawlId, reportTemplateCode: "broken_pages" }
  ) {
    reportTemplate {
      code
      name
    }
    basic
    crawlUrls(first: 3) {
      nodes {
        url
        httpStatusCode
      }
      totalCount
    }
  }
}
```

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

**Response:**
```json
{
  "data": {
    "getReportStat": {
      "reportTemplate": {
        "code": "broken_pages",
        "name": "Broken Pages"
      },
      "basic": 12,
      "crawlUrls": {
        "nodes": [
          {
            "url": "https://www.example.com/old-page",
            "httpStatusCode": 404
          },
          {
            "url": "https://www.example.com/removed",
            "httpStatusCode": 410
          },
          {
            "url": "https://www.example.com/error",
            "httpStatusCode": 500
          }
        ],
        "totalCount": 12
      }
    }
  }
}
```

The `basic` field on a `ReportStat` represents the primary metric count for that report (e.g., the number of broken pages). You can then paginate through `crawlUrls` to see the individual URLs that match the report filter.

## Priority and impact

Some report templates include `changeWeight` and `changeSign` fields that indicate how changes in this report should be interpreted:

- A positive `changeSign` means an increase is an improvement.
- A negative `changeSign` means an increase is a regression.
- `changeWeight` indicates the relative importance of this report compared to others.

These values are used internally for health score calculations and can help you prioritise which reports to focus on.

## Choosing the right datasource

When building custom queries or report downloads, use this decision tree:

1. **Page-level metrics** (status codes, titles, word count, etc.) -- use `CrawlUrls`.
2. **Link analysis** (broken links, redirect chains, anchor text) -- use `CrawlLinks`.
3. **Sitemap analysis** -- use `CrawlSitemaps`.
4. **International SEO** (hreflang issues) -- use `CrawlHreflangs`.
5. **Accessibility auditing** -- use `CrawlAccessibilityIssues` or `CrawlAccessibilityIssueInstances`.
6. **Site speed** -- use `CrawlSiteSpeedAudits`.
7. **Search performance** -- use `CrawlSearchQueries`.