Search and filter cases

This page complements the Cases GraphQL API guide. Use it for QL filters and pagination options.

For the workflow around creating, updating, and closing cases, see Manage the case lifecycle.

Cases use the same QL syntax as Advanced Search.

What this covers¶

This guide shows how to search cases with filters, sorting, and pagination. Use it when you need a case list rather than a single case by ID.

Prerequisites¶

• Create a service principal and get a bearer token. See the Cases GraphQL quickstart.
• Resolve tenant-specific type and status IDs before you filter by them.
• Choose offset or cursor pagination for each request.

Workflow¶

Searching cases with the Cases GraphQL API consists of the following steps:

1. Build a cases query with the fields that your integration needs.
2. Add a QL filter and sort expression.
3. Page through the results with offset or cursor pagination.
4. Use the returned IDs in follow-up case operations.

Search cases¶

Query available cases by title, severity, status, dates, and more.

Query¶

query searchCases($arguments: CasesArguments!) {
    cases(arguments: $arguments) {
        cases {
            id
            shortId
            title
            severity
            type {
                id
                name
            }
            primaryStatus {
                id
                name
            }
            tags
            assigneeId
            createdAt
            updatedAt
        }
        totalCount
        pageInfo {
            startCursor
            endCursor
            hasNextPage
            hasPreviousPage
        }
    }
}

Variables¶

Search with a query:

{
    "arguments": {
        "query": "title contains 'suspicious login'",
        "pagination": {
            "offset": {
                "page": 1,
                "perPage": 20
            }
        }
    }
}

Response example¶

{
    "data": {
        "cases": {
            "cases": [
                {
                    "id": "<case-id>",
                    "shortId": "CSE00001",
                    "title": "Suspicious login detected",
                    "severity": 8,
                    "type": {
                        "id": "<type-id>",
                        "name": "investigation"
                    },
                    "primaryStatus": {
                        "id": "<open-status-id>",
                        "name": "NEW"
                    },
                    "tags": ["investigation"],
                    "assigneeId": "<user-id>",
                    "createdAt": "2024-08-14T16:00:00Z",
                    "updatedAt": "2024-08-14T16:05:00Z"
                }
            ],
            "totalCount": 1,
            "pageInfo": {
                "startCursor": "<start-cursor>",
                "endCursor": "<end-cursor>",
                "hasNextPage": false,
                "hasPreviousPage": false
            }
        }
    }
}

Check pageInfo.hasNextPage to find out whether more pages are available. For cursor pagination, pass pageInfo.endCursor as the next request's after value.

Query syntax¶

Basic query structure¶

[where] <field> <operator> <value> [and <field> <operator> <value> ...] [| sort <field> [asc|desc]]

The where keyword is optional.

Searchable fields¶

Comparison operators¶

Logical operators¶

Combine conditions with and:

title contains 'suspicious' and severity >= 6 and closedAt is null

String values¶

Enclose strings in single quotes:

title contains 'phishing attack'

Array fields (tags)¶

Match cases where tags contain specific values:

tags contains 'malware'
tags in ('malware', 'phishing', 'ransomware')

Sort¶

Order results with the | sort operator:

title contains 'phishing' | sort severity desc
title contains 'phishing' | sort createdAt asc

Default sort order is createdAt desc (newest first).

Time ranges¶

Filter by time range using ISO 8601 timestamps:

createdAt >= '2024-08-01T00:00:00Z' and createdAt <= '2024-08-31T23:59:59Z'

Query examples¶

Find open critical cases¶

{
    "arguments": {
        "query": "severity = 10 and closedAt is null",
        "pagination": {"offset": {"page": 1, "perPage": 20}}
    }
}

Search by title¶

{
    "arguments": {
        "query": "title contains 'ransomware'",
        "pagination": {"offset": {"page": 1, "perPage": 50}}
    }
}

Filter by tag¶

{
    "arguments": {
        "query": "tags contains 'malware' and severity >= 6",
        "pagination": {"offset": {"page": 1, "perPage": 20}}
    }
}

Find recently updated cases¶

{
    "arguments": {
        "query": "updatedAt >= '2024-08-14T00:00:00Z' | sort updatedAt desc",
        "pagination": {"offset": {"page": 1, "perPage": 20}}
    }
}

Assigned to a specific user¶

{
    "arguments": {
        "query": "assigneeId = '550e8400-e29b-41d4-a716-446655440010'",
        "pagination": {"offset": {"page": 1, "perPage": 20}}
    }
}

Pagination¶

Both offset (page-based) and cursor pagination are supported.

Offset pagination¶

{
    "arguments": {
        "pagination": {
            "offset": {
                "page": 1,
                "perPage": 20
            }
        }
    }
}

• page: 1-indexed page number (default: 1)
• perPage: Results per page, max 100 (default: 20)

Cursor pagination¶

{
    "arguments": {
        "pagination": {
            "cursor": {
                "first": 20,
                "after": "cursor_value_here"
            }
        }
    }
}

• first: Forward page size, max 100 (default: 20)
• after: Cursor from previous page's endCursor

Use last and before for backward traversal.

Important notes¶

• Filter by IDs: Case search doesn't support display-name filters such as caseType.name or primaryStatus.name. Query caseTypes and casePrimaryStatuses first, then filter by fields such as typeId and primaryStatusId.
• Empty query: Omit query to retrieve all cases. The default sort order is newest first.
• Default pagination: When you omit pagination, the API returns page 1 with 20 results.
• Opaque cursors: Don't parse cursor values. Use each cursor exactly as the API returns it.

Next steps¶

For more information, see the Cases GraphQL API guide or Manage the case lifecycle.

Error handling¶

Check the HTTP status and the GraphQL response body. A request can return HTTP 200 with an errors array.

Invalid QL fields or operators return a GraphQL error. Use the documented flat fields and resolve type or status names to IDs before you retry.

Constraints and considerations¶

• Offset and cursor pagination are alternatives. Do not send both in one request.
• perPage, first, and last have a maximum of 100.
• Cursors are opaque. Store and reuse them without parsing.
• An omitted query returns all cases that the caller can access.

Related operations¶

• Cases GraphQL API guide
• Manage the case lifecycle
• Manage case comments
• cases
• caseTypes
• casePrimaryStatuses