Filtering

To filter results, we use the filter argument. It takes the ConnectionFilterInput corresponding to the entity we're retrieving as a value. These inputs are defined as:

input ExampleConnectionFilterInput {
  _and: [ExampleConnectionFilterInput!]
  _or: [ExampleConnectionFilterInput!]
  url: ConnectionStringFilterInput
  # ...and so on for other field types like Boolean, Date, Int etc.
}

Each field in the ConnectionFilterInput can be filtered by a subset of predicates available for the given data type. The sections below list every predicate grouped by type.

String predicates

ConnectionStringFilterInput -- used for text fields such as URLs, names, and descriptions.

Predicate	Type	Description
`eq`	`String`	Exact match.
`ne`	`String`	Not equal.
`contains`	`String`	Field contains the substring.
`notContains`	`String`	Field does not contain the substring.
`beginsWith`	`String`	Field starts with the value.
`endsWith`	`String`	Field ends with the value.
`matchesRegex`	`String`	Field matches the regular expression.
`notMatchesRegex`	`String`	Field does not match the regular expression.
`in`	`[String!]`	Field value is one of the provided values.
`notIn`	`[String!]`	Field value is not one of the provided values.
`isEmpty`	`Boolean`	When `true`, matches empty strings. When `false`, matches non-empty strings.
`isNull`	`Boolean`	When `true`, matches `null` values. When `false`, matches non-null values.

Examples:

# URLs containing "blog"
filter: { url: { contains: "blog" } }

# URLs starting with "https://example.com"
filter: { url: { beginsWith: "https://example.com" } }

# Match a regex pattern
filter: { url: { matchesRegex: "^https://[^/]+/products/\\d+" } }

# One of several exact values
filter: { name: { in: ["Google", "Wikipedia", "GitHub"] } }

Numeric predicates (Int, Float, BigInt)

ConnectionIntFilterInput, ConnectionFloatFilterInput, and ConnectionBigIntFilterInput share the same set of predicates.

Predicate	Type	Description
`eq`	`Int`	Equal to.
`ne`	`Int`	Not equal to.
`gt`	`Int`	Greater than.
`ge`	`Int`	Greater than or equal to.
`lt`	`Int`	Less than.
`le`	`Int`	Less than or equal to.
`in`	`[Int!]`	Value is one of the provided values.
`notIn`	`[Int!]`	Value is not one of the provided values.
`isNull`	`Boolean`	When `true`, matches `null` values.

Examples:

# Pages returning a 404
filter: { httpStatusCode: { eq: 404 } }

# Pages with more than 100 inlinks
filter: { inLinksInternalCount: { gt: 100 } }

# Status codes in a set
filter: { httpStatusCode: { in: [301, 302, 307] } }

# Combine range predicates for a between filter
filter: { pageSize: { ge: 1000, le: 5000 } }

Boolean predicates

ConnectionBooleanFilterInput -- used for true/false fields.

Predicate	Type	Description
`eq`	`Boolean`	Matches `true` or `false`.
`ne`	`Boolean`	Does not match the given value.
`isNull`	`Boolean`	When `true`, matches `null` values.

Example:

# Pages without structured data
filter: { hasStructuredData: { eq: false } }

Date predicates

ConnectionDateFilterInput -- used for timestamp fields such as createdAt and updatedAt.

Predicate	Type	Description
`eq`	`DateTime`	Exact date match.
`ne`	`DateTime`	Not equal.
`gt`	`DateTime`	After the given date.
`ge`	`DateTime`	On or after the given date.
`lt`	`DateTime`	Before the given date.
`le`	`DateTime`	On or before the given date.
`in`	`[DateTime!]`	One of the provided dates.
`notIn`	`[DateTime!]`	Not one of the provided dates.
`isNull`	`Boolean`	When `true`, matches `null` values.

Example:

# Projects created after Jan 1 2025
filter: { createdAt: { gt: "2025-01-01T00:00:00Z" } }

Enum predicates

Enum fields (e.g. CrawlStatus, CrawlPriority) use dedicated filter inputs that follow the same pattern.

Predicate	Type	Description
`eq`	`<EnumType>`	Exact match on enum value.
`ne`	`<EnumType>`	Not equal.
`in`	`[<EnumType>!]`	Value is one of the provided enum values.
`notIn`	`[<EnumType>!]`	Value is not one of the provided enum values.
`isNull`	`Boolean`	When `true`, matches `null` values.

Example:

# Only finished crawls
filter: { status: { eq: Finished } }

# Crawls that are queued or running
filter: { status: { in: [Queued, Running] } }

Array predicates

ConnectionIntArrayFilterInput and ConnectionStringArrayFilterInput -- used for array-valued fields.

Predicate	Type	Description
`arrayContains`	`String` / `Int`	Array includes the given element.
`arrayNotContains`	`String` / `Int`	Array does not include the given element.
`arrayContainsLike`	`String`	Array includes an element containing the value, case-insensitively (string arrays only).
`arrayNotContainsLike`	`String`	Array includes no element containing the value, case-insensitively (string arrays only).
`isNull`	`Boolean`	When `true`, matches `null` values.

The Like predicates are substring matches, not glob patterns — * and ? in the value are matched literally.

Example:

# Pages that have a specific tag in their tags array
filter: { tags: { arrayContains: "navigation" } }

# Pages with any tag under the "nav-" prefix
filter: { tags: { arrayContainsLike: "nav-" } }

Object array predicates

Some fields hold an array of objects rather than an array of scalars — for example crawlUrls.schemaIssuesCountByType, which stores one { schemaType, errorsCount, warningsCount } entry per schema type that carries a validation issue on the page. These fields take a member filter input instead of a predicate object: you name the member you want to filter on, and give it array predicates.

String members take ConnectionStringObjectArrayMemberFilterInput (arrayContains, arrayNotContains, arrayContainsLike, arrayNotContainsLike); integer and float members take the Int/Float variants, which offer arrayContains and arrayNotContains only. There are no range predicates (gt, lt, ...) on object array members.

# Pages where the Merchant listing schema type has at least one issue.
# The array only holds types that actually carry an issue, so presence is the filter.
filter: { schemaIssuesCountByType: { schemaType: { arrayContains: "Merchant listing" } } }

# Pages where some schema type has exactly two errors
filter: { schemaIssuesCountByType: { errorsCount: { arrayContains: 2 } } }

Members are matched independently

Predicates on two different members are not correlated to the same array entry. This filter:

filter: {
  schemaIssuesCountByType: {
    schemaType: { arrayContains: "Merchant listing" }
    errorsCount: { arrayContains: 2 }
  }
}

matches a page that has a Merchant listing entry and an entry with two errors — they need not be the same entry. There is no way to require that a single entry satisfies every predicate. Where an entity exposes an equivalent page-level metric (here schemaErrorsCount), filtering on that alongside a single member predicate is usually closer to what you want.

Combining filters with `_and` and `_or`

The _and and _or arrays are special properties allowing you to write more complex filters. ConnectionFilterInput objects in the _and array are combined using logical AND operator, and those inside _or array are combined using logical OR operator. All root-level conditions are always combined using logical AND operator. That means a filter such as this:

{
  _and: [
    { sitemapsInCount: { eq: 0 } }
  ],
  _or: [
    { url: { contains: "news" } },
    { url: { contains: "guides" } }
  ],
  hasStructuredData: { eq: false }
}

is exactly the same as:

{
  _and: [
    { sitemapsInCount: { eq: 0 } },
    {
      _or: [
        { url: { contains: "news" } },
        { url: { contains: "guides" } }
      ]
    },
    { hasStructuredData: { eq: false } },
  ]
}

Nesting `_and` inside `_or` (and vice versa)

You can nest logical operators to express arbitrarily complex conditions:

filter: {
  _or: [
    {
      _and: [
        { httpStatusCode: { eq: 200 } },
        { pageSize: { gt: 50000 } }
      ]
    },
    {
      _and: [
        { httpStatusCode: { eq: 301 } },
        { redirectUrl: { contains: "legacy" } }
      ]
    }
  ]
}

This returns pages that are either (200 AND large) or (301 AND redirecting to a legacy URL).

Multiple predicates on the same field

You can apply more than one predicate to a single field to create range filters:

filter: {
  httpStatusCode: { ge: 400, lt: 500 }
}

This returns all pages with a 4xx client error status code.

Example -- Getting Projects with a filter

Operation: query getAccount($id: ObjectID!) { getAccount(id: $id) { projects( filter: { _or: [{ name: { eq: "Google" } }, { name: { eq: "Wikipedia" } }] } ) { nodes { name } } } }Variables: { "id": 123 }Response Example: { "data": { "getAccount": { "projects": { "nodes": [ { "name": "Google" }, { "name": "Wikipedia" } ] } } } }

getAccountTry in Explorer

GraphQL

query getAccount($id: ObjectID!) {
  getAccount(id: $id) {
    projects(
      filter: {
        _or: [{ name: { eq: "Google" } }, { name: { eq: "Wikipedia" } }]
      }
    ) {
      nodes {
        name
      }
    }
  }
}

Example -- Complex filtering on crawl URLs

The following example combines _and and _or to filter crawl URLs that are HTTP 200 and belong to either the /blog/ or /news/ path:

Operation: query FilteredCrawlUrls($crawlId: ObjectID!) { getReportStat( input: { crawlId: $crawlId, reportTemplateCode: "all_pages" } ) { crawlUrls( first: 5 filter: { _and: [ { httpStatusCode: { eq: 200 } } { _or: [ { url: { contains: "/blog/" } } { url: { contains: "/news/" } } ] } ] } ) { nodes { url httpStatusCode } totalCount } } }Variables: { "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ" }Response Example: { "data": { "getReportStat": { "crawlUrls": { "nodes": [ { "url": "https://www.example.com/blog/seo-tips", "httpStatusCode": 200 }, { "url": "https://www.example.com/news/latest-update", "httpStatusCode": 200 } ], "totalCount": 42 } } } }

FilteredCrawlUrlsTry in Explorer

GraphQL

query FilteredCrawlUrls($crawlId: ObjectID!) {
  getReportStat(
    input: { crawlId: $crawlId, reportTemplateCode: "all_pages" }
  ) {
    crawlUrls(
      first: 5
      filter: {
        _and: [
          { httpStatusCode: { eq: 200 } }
          {
            _or: [
              { url: { contains: "/blog/" } }
              { url: { contains: "/news/" } }
            ]
          }
        ]
      }
    ) {
      nodes {
        url
        httpStatusCode
      }
      totalCount
    }
  }
}

String predicates​

Numeric predicates (Int, Float, BigInt)​

Boolean predicates​

Date predicates​

Enum predicates​

Array predicates​

Object array predicates​

Combining filters with _and and _or​

Nesting _and inside _or (and vice versa)​

Multiple predicates on the same field​

Example -- Getting Projects with a filter​

Example -- Complex filtering on crawl URLs​

String predicates

Numeric predicates (Int, Float, BigInt)

Boolean predicates

Date predicates

Enum predicates

Array predicates

Object array predicates

Combining filters with `_and` and `_or`

Nesting `_and` inside `_or` (and vice versa)

Multiple predicates on the same field

Example -- Getting Projects with a filter

Example -- Complex filtering on crawl URLs