Segments

Segments allow you to partition your crawl data into meaningful subsets based on URL filters. For example, you might create segments for blog pages, product pages, or pages within a specific subdirectory.

What segments are

A segment is a named filter applied to crawl URLs within a project. Once created, Lumar generates segment-specific data after each crawl, allowing you to track metrics and health scores for that subset of pages independently.

Key properties of a segment:

• name -- a descriptive label (e.g., "Blog Pages").
• group -- an optional grouping label for organising related segments.
• crawlUrlFilter -- a JSON filter object using the same predicate syntax as CrawlUrlConnectionFilterInput.

Creating a segment

Use the createCrawlUrlSegment mutation to define a new segment on a project.

Operation: mutation CreateCrawlUrlSegment($input: CreateCrawlUrlSegmentInput!) { createCrawlUrlSegment(input: $input) { segment { id name group crawlUrlFilter createdAt } } }Variables: { "input": { "projectId": "TjAwN1Byb2plY3Q2MTMy", "name": "Blog Pages", "group": "Content", "crawlUrlFilter": { "url": { "contains": "/blog/" } } } }Response Example: { "data": { "createCrawlUrlSegment": { "segment": { "id": "TjAyMVNlZ21lbnQx", "name": "Blog Pages", "group": "Content", "crawlUrlFilter": { "url": { "contains": "/blog/" } }, "createdAt": "2025-01-15T10:00:00.000Z" } } } }

CreateCrawlUrlSegmentTry in Explorer

GraphQL

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

The crawlUrlFilter uses the same filter syntax as the filter argument on crawl URL connections. See Filtering for the full predicate reference.

Querying segments

Retrieve all segments defined on a project:

Operation: query GetProjectSegments($projectId: ObjectID!) { getProject(id: $projectId) { segments(first: 10) { nodes { id name group crawlUrlFilter createdAt } totalCount } } }Response Example: { "data": { "getProject": { "segments": { "nodes": [ { "id": "TjAyMVNlZ21lbnQx", "name": "Blog Pages", "group": "Content", "crawlUrlFilter": { "url": { "contains": "/blog/" } }, "createdAt": "2025-01-10T08:00:00.000Z" }, { "id": "TjAyMVNlZ21lbnQy", "name": "Product Pages", "group": "Commerce", "crawlUrlFilter": { "url": { "contains": "/products/" } }, "createdAt": "2025-01-10T08:30:00.000Z" } ], "totalCount": 2 } } } }

GetProjectSegmentsTry in Explorer

GraphQL

query GetProjectSegments($projectId: ObjectID!) {
  getProject(id: $projectId) {
    segments(first: 10) {
      nodes {
        id
        name
        group
        crawlUrlFilter
        createdAt
      }
      totalCount
    }
  }
}

Segment health scores

Once a segment is created and a crawl completes, you can query health scores scoped to that segment. Pass the segmentId to the healthScore field on a crawl:

Operation: query GetSegmentHealthScore($crawlId: ObjectID!, $segmentId: ObjectID!) { getCrawl(id: $crawlId) { healthScore(reportCategoryCode: "seo", segmentId: $segmentId) { healthScore reportCategoryCode segmentId } } }Variables: { "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ", "segmentId": "TjAyMVNlZ21lbnQx" }Response Example: { "data": { "getCrawl": { "healthScore": [ { "healthScore": 88.2, "reportCategoryCode": "seo", "segmentId": "TjAyMVNlZ21lbnQx" } ] } } }

GetSegmentHealthScoreTry in Explorer

GraphQL

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

You can also track segment health scores over time using getHealthScoreTrendForCrawlSegment, which works like getHealthScoreTrendForCrawl but accepts an additional segmentId parameter.

Reports without per-segment data

A segment adds a calculation for every report on the project, so a project with many segments and many reports produces a large number of per-segment results -- most of which are never looked at. Individual reports can therefore opt out of per-segment generation via skipSegmentGeneration, available on both ReportTemplate and CustomReportTemplate.

When a report has skipSegmentGeneration: true:

• Its crawl-level report and report stat are generated as normal.
• Its rows can still be filtered by segment when you query them, so the report stays usable per segment.
• No per-segment report stat is generated, so there is no per-segment trend for it.

Practical consequences when querying:

• getReportStat with a segmentId returns null for a crawl in which the report was opted out, and the report is omitted from getReportStats results scoped to a segment. This is not an error.
• The flag applies when a crawl's reports are generated, so it describes what future crawls will produce rather than what already exists. A report that is opted out today can still have per-segment data from earlier crawls, and a report that is opted in today can have gaps from crawls that ran while it was opted out. Treat a segmented trend as potentially sparse and handle missing points per crawl -- do not read skipSegmentGeneration to decide whether a trend exists at all, or you will hide data that was legitimately generated.
• Opting a report out does not remove per-segment data already generated for earlier crawls, but regenerating an earlier crawl's reports rebuilds them under the report's current setting.

Custom reports set the flag through createCustomReportTemplate / updateCustomReportTemplate. Reports shipped by a custom metric container declare it in the container definition and cannot be changed through the API.

Use cases

Use Case	Segment Filter Example
Blog content	{ "url": { "contains": "/blog/" } }
Product pages	{ "url": { "contains": "/products/" } }
Subdomain	{ "url": { "beginsWith": "https://shop.example.com" } }
Non-indexable pages	{ "indexable": { "eq": false } }
Large pages	{ "pageSize": { "gt": 100000 } }

Segments are especially useful when combined with health scores and dashboards to monitor specific areas of your site independently.