# Segments

https://api-docs.lumar.io/docs/graphql/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.

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

The `crawlUrlFilter` uses the same filter syntax as the `filter` argument on crawl URL connections. See [Filtering](filtering) for the full predicate reference.

## Querying segments

Retrieve all segments defined on a project:

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

**Response:**
```json
{
  "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
      }
    }
  }
}
```

## 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:

```graphql
query GetSegmentHealthScore($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"
        }
      ]
    }
  }
}
```

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

## 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.