Version:

Version:

Version:

Version:


Table of Contents

API Guide

Download PDF
Copy Link

Query API Reference

API Routes

Apply Basic Query

GET /api/3/{collection}?param1=value&param2=value

For more information, see API Endpoints Reference chapter.

Apply Ad Hoc Query

POST /api/query/{collection}
BODY:
{ QUERY OBJECT }
  • The collection parameter matches the collection route in the typical CRUD API (/api/3/{collection})

Example

POST /api/query/incidents
BODY:
{
  "logic": "AND",
  "filters": [
    {
      "field": "status.itemValue",
      "operator": "eq",
      "value": "Open"
    }
  ]
}

Apply Persisted Query

GET /api/query/{collection}/{queryId}
  • The collection parameter matches the collection route in the typical CRUD API (/api/3/{collection})
  • The queryId parameter matches a Query Object UUID stored in /api/3/query_objects

Example

GET /api/query/incidents/2e77a714-f0c1-45ca-bd49-b71efbd9328c

Query Objects

Filter

A filter contains a field, operator, and a value.

{
"field": "{fieldName}",
"operator": "{operator}",
"value": {value}
}

Field

The field can be any valid field in the module. To access sub-elements of a relationship or picklist field, you can use dot notation or double-underscore notation.

"field": "name"
"field": "status.itemValue"
"field": "assignedToPerson.email"

Operator

The operator can be any of the available operators for a specific field type.

"operator": "eq"
"operator": "like"

For the complete list of supported operations, see the Supported Field Operators section.

Value

The value is the object of the filter or comparison. For example, if you are using the is like operator, then the value will be a pattern to match the record field.

"operator": "eq",
"value": "Alert 123: Repeated login failures - device xxx"
 
"operator": "like",
"value": "alert ___: Repeated login failures%"

For the complete list of supported operations, see the Supported Field Operators section.

Supported Field Operators

Operator Value Syntax Description
eq string Equals: Field is an exact match.
neq string Not Equals: Field is not an exact match.
lt number Less Than: Field has a lesser than value. In the case of Date/Time fields this translates to "Before", i.e. the date field is before the specified date.
lte number Less Than or Equal To: Field has a lesser than or equal to value. In the case of Date/Time fields this translates to "On or Before", i.e. the date field is on or after the specified date.
gt number Greater Than: Field has a greater than value. In the case of Date/Time fields this translates to "After", i.e. the date field is after the specified date.
gte number Greater Than or Equal To: Field has a greater than or equal to value. In the case of Date/Time fields this translates to "On or After", i.e. the date field is on the specified date or after the specified date.
in value1 | value2 ... In: Field is in the given list of values.
nin value1 | value2 ... Not In: Field is not in the given list of values.
contains string Contains: Object contains the key. Only applicable for field type Object.
like string pattern Like: Field matches the given pattern. The pattern can contain text, percent (%), or an underscrore (_)
% represents zero or more of any characters.
_ represents one character.
notlike string pattern Not Like: Field does not match the given pattern. The pattern can contain text, percent (%), or an underscrore (_)
% represents zero or more of any characters.
_ represents one character.
isnull boolean Is Null: If value is set as true, then this checks if the field is null. If value is set as false, then this checks if the field is not null.

Logic

AND

A collection of filters can be applied in conjunction using "logic": "AND"

Example

Query all records where record.assignedToUser !== null && record.status === "Open"

{
  "logic": "AND",
  "filters": [
    {
      "field": "assignedToUser",
      "operator": "isnull",
      "value": false
    },
    {
      "field": "status",
      "operator": "eq",
      "value": "Open"
    }
  ]
}

OR

A collection of filters can be applied in disjunction using "logic": "OR"

Example

Query all records where record.status === "Open" || record.status === "Pending"

{
  "logic": "OR",
  "filters": [
    {
      "field": "status",
      "operator": "eq",
      "value": "Open"
    },
    {
      "field": "status",
      "operator": "eq",
      "value": "Pending"
    }
  ]
}

Nested Logic

Nesting logic filters allows you to build queries with nested logic like conditionX && (conditionY || conditionZ)

Example

Query all records where record.assignedToUser !== null && (record.status === "Open" || record.status === "Pending")

{
  "logic": "AND",
  "filters": [
    {
      "field": "assignedToUser",
      "operator": "isnull",
      "value": false
    },
    {
      "logic": "OR",
      "filters": [
        {
          "field": "status",
          "operator": "eq",
          "value": "Open"
        },
        {
          "field": "status",
          "operator": "eq",
          "value": "Pending"
        }
      ]
    }
  ]
}

Sort

Records can be sorted by field/direction using the "sort": [] list. This list contains objects with "field" and "direction" keys. The "field" key identifies which field (or association) to sort by. The "direction" key identifies whether to sort ascending ("ASC") or descending ("DESC"). Order is maintained when applying these sorts.

{
  "logic": "AND",
  "filters": [],
  "sort": [
    {
      "field": "createDate",
      "direction": "DESC"
    }
  ]
}

Aggregation

Records can be aggregated using the "aggregates": [] list. This list contains objects with "operator", "field", and "alias" keys. The "operator" key identifies which aggregate operator to apply to the specified field. The "field" key identifies the field to apply it to. The "alias" key identifies what the returned field looks like.

Supported Aggregate Operators

  • fields
  • select
  • count
  • countdistinct
  • groupby
  • distinct
  • sum
  • max
  • min
  • median
  • avg

Examples

Count all records in each status grouping
{
  "logic": "AND",
  "filters": [],
  "aggregates": [
    {
      "operator": "groupby",
      "field": "status",
      "alias": "status"
    },
    {
      "operator": "countdistinct",
      "field": "*",
      "alias": "total"
    }
  ]
}
Average 'resolve' time between an incident's 'closed' and 'resolved' date

The following sample API gives you the 'Average' for the 'resolve' time between an incident's closed and resolved date. You can optionally add additional filters if required.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "filters": [
        {
            "logic": "AND",
            "filters": [
                {
                    "field": "resolveddate",
                    "operator": "gte",
                    "type": "primitive",
                    "value": "2022-04-22T09:39:39.358Z"
                },
                {
                    "field": "resolveddate",
                    "operator": "lte",
                    "type": "primitive",
                    "value": "2022-05-22T09:39:39.358Z"
                }
            ],
            "type": "datetime"
        }
    ],
    "aggregates": [
        {
            "operator": "avg",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:00:37.071302"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Total time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Sum' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "sum",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Minimum time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Min' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "min",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Maximum time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Max' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "max",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Median time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Median' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "median",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}

Associations

Wherever a "field" key is specified in a query object, you can use dot-notation to query against an associated entity using the same operators that are available for the root record.

Example

Query all records assigned to a user named Jeff.

{
  "logic": "AND",
  "filters": [
    {
      "field": "assignedToUser.firstname",
      "operator": "eq",
      "value": "Jeff"
    }
  ]
}

Model Type

Use this API to search for records from different models like Incident, Alerts or any other custom models based on multiple valid fields in the model.

The API is: https://{{hostname}}/api/query/{{modelType}}. For example, https://{{hostname}}/api/query/incidents where incidents is a model in which you want to search for records. This API uses POST as the request method.

Example

BODY: 
{
    "aggregates": [
        {
            "operator": "groupby",
            "field": "phase.itemValue",
            "alias": "phase"
        },
        {
            "operator": "avg",
            "field": "dwellTime",
            "alias": "maxDwellTime"
        }
    ],
    "logic": "AND",
    "filters": []
}

Response: JSON list of records matching the filter criteria provided in the BODY of the modelType.

Get only specified fields in the API response body while querying a module

Use the "__selectFields" parameter in the request body of 'query' APIs such as /api/query/alerts, to get only the fields you have specified in the API response body when you exporting or fetching alert records using the API.

Example

__selectFields: ["id", "severity"]

Response: The API response body will contain only the "id" and "severity" fields when you exporting or fetching alert records using the API.

Ignore specified fields from the API response body while querying a module

Use the "__ignoreFields" parameter in the request body of 'query' APIs such as /api/query/alerts, to ignore the fields you have specified from the API response body when you exporting or fetching alert records using the API.

Example

__ignoreFields: ["createDate", "createUser"]

Response: The API response body of the exported alert records will contain all fields except the "createDate" and "createUser" fields.

Query API Reference

API Routes

Apply Basic Query

GET /api/3/{collection}?param1=value&param2=value

For more information, see API Endpoints Reference chapter.

Apply Ad Hoc Query

POST /api/query/{collection}
BODY:
{ QUERY OBJECT }
  • The collection parameter matches the collection route in the typical CRUD API (/api/3/{collection})

Example

POST /api/query/incidents
BODY:
{
  "logic": "AND",
  "filters": [
    {
      "field": "status.itemValue",
      "operator": "eq",
      "value": "Open"
    }
  ]
}

Apply Persisted Query

GET /api/query/{collection}/{queryId}
  • The collection parameter matches the collection route in the typical CRUD API (/api/3/{collection})
  • The queryId parameter matches a Query Object UUID stored in /api/3/query_objects

Example

GET /api/query/incidents/2e77a714-f0c1-45ca-bd49-b71efbd9328c

Query Objects

Filter

A filter contains a field, operator, and a value.

{
"field": "{fieldName}",
"operator": "{operator}",
"value": {value}
}

Field

The field can be any valid field in the module. To access sub-elements of a relationship or picklist field, you can use dot notation or double-underscore notation.

"field": "name"
"field": "status.itemValue"
"field": "assignedToPerson.email"

Operator

The operator can be any of the available operators for a specific field type.

"operator": "eq"
"operator": "like"

For the complete list of supported operations, see the Supported Field Operators section.

Value

The value is the object of the filter or comparison. For example, if you are using the is like operator, then the value will be a pattern to match the record field.

"operator": "eq",
"value": "Alert 123: Repeated login failures - device xxx"
 
"operator": "like",
"value": "alert ___: Repeated login failures%"

For the complete list of supported operations, see the Supported Field Operators section.

Supported Field Operators

Operator Value Syntax Description
eq string Equals: Field is an exact match.
neq string Not Equals: Field is not an exact match.
lt number Less Than: Field has a lesser than value. In the case of Date/Time fields this translates to "Before", i.e. the date field is before the specified date.
lte number Less Than or Equal To: Field has a lesser than or equal to value. In the case of Date/Time fields this translates to "On or Before", i.e. the date field is on or after the specified date.
gt number Greater Than: Field has a greater than value. In the case of Date/Time fields this translates to "After", i.e. the date field is after the specified date.
gte number Greater Than or Equal To: Field has a greater than or equal to value. In the case of Date/Time fields this translates to "On or After", i.e. the date field is on the specified date or after the specified date.
in value1 | value2 ... In: Field is in the given list of values.
nin value1 | value2 ... Not In: Field is not in the given list of values.
contains string Contains: Object contains the key. Only applicable for field type Object.
like string pattern Like: Field matches the given pattern. The pattern can contain text, percent (%), or an underscrore (_)
% represents zero or more of any characters.
_ represents one character.
notlike string pattern Not Like: Field does not match the given pattern. The pattern can contain text, percent (%), or an underscrore (_)
% represents zero or more of any characters.
_ represents one character.
isnull boolean Is Null: If value is set as true, then this checks if the field is null. If value is set as false, then this checks if the field is not null.

Logic

AND

A collection of filters can be applied in conjunction using "logic": "AND"

Example

Query all records where record.assignedToUser !== null && record.status === "Open"

{
  "logic": "AND",
  "filters": [
    {
      "field": "assignedToUser",
      "operator": "isnull",
      "value": false
    },
    {
      "field": "status",
      "operator": "eq",
      "value": "Open"
    }
  ]
}

OR

A collection of filters can be applied in disjunction using "logic": "OR"

Example

Query all records where record.status === "Open" || record.status === "Pending"

{
  "logic": "OR",
  "filters": [
    {
      "field": "status",
      "operator": "eq",
      "value": "Open"
    },
    {
      "field": "status",
      "operator": "eq",
      "value": "Pending"
    }
  ]
}

Nested Logic

Nesting logic filters allows you to build queries with nested logic like conditionX && (conditionY || conditionZ)

Example

Query all records where record.assignedToUser !== null && (record.status === "Open" || record.status === "Pending")

{
  "logic": "AND",
  "filters": [
    {
      "field": "assignedToUser",
      "operator": "isnull",
      "value": false
    },
    {
      "logic": "OR",
      "filters": [
        {
          "field": "status",
          "operator": "eq",
          "value": "Open"
        },
        {
          "field": "status",
          "operator": "eq",
          "value": "Pending"
        }
      ]
    }
  ]
}

Sort

Records can be sorted by field/direction using the "sort": [] list. This list contains objects with "field" and "direction" keys. The "field" key identifies which field (or association) to sort by. The "direction" key identifies whether to sort ascending ("ASC") or descending ("DESC"). Order is maintained when applying these sorts.

{
  "logic": "AND",
  "filters": [],
  "sort": [
    {
      "field": "createDate",
      "direction": "DESC"
    }
  ]
}

Aggregation

Records can be aggregated using the "aggregates": [] list. This list contains objects with "operator", "field", and "alias" keys. The "operator" key identifies which aggregate operator to apply to the specified field. The "field" key identifies the field to apply it to. The "alias" key identifies what the returned field looks like.

Supported Aggregate Operators

  • fields
  • select
  • count
  • countdistinct
  • groupby
  • distinct
  • sum
  • max
  • min
  • median
  • avg

Examples

Count all records in each status grouping
{
  "logic": "AND",
  "filters": [],
  "aggregates": [
    {
      "operator": "groupby",
      "field": "status",
      "alias": "status"
    },
    {
      "operator": "countdistinct",
      "field": "*",
      "alias": "total"
    }
  ]
}
Average 'resolve' time between an incident's 'closed' and 'resolved' date

The following sample API gives you the 'Average' for the 'resolve' time between an incident's closed and resolved date. You can optionally add additional filters if required.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "filters": [
        {
            "logic": "AND",
            "filters": [
                {
                    "field": "resolveddate",
                    "operator": "gte",
                    "type": "primitive",
                    "value": "2022-04-22T09:39:39.358Z"
                },
                {
                    "field": "resolveddate",
                    "operator": "lte",
                    "type": "primitive",
                    "value": "2022-05-22T09:39:39.358Z"
                }
            ],
            "type": "datetime"
        }
    ],
    "aggregates": [
        {
            "operator": "avg",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:00:37.071302"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Total time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Sum' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "sum",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Minimum time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Min' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "min",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Maximum time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Max' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "max",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}
Median time taken between when an incident is created and when it is resolved

The following sample API gives you the 'Median' of an incident's 'create' and 'resolve' date.

Request

URL: https://<Host>/api/query/incidents?$limit=30

BODY:

{
    "sort": [],
    "limit": 30,
    "logic": "AND",
    "aggregates": [
        {
            "operator": "median",
            "field": "resolveddate,createDate",
            "alias": "value"
        }
    ]
}

Response:

{
    "@context": "/api/3/contexts/Incident",
    "@id": "/api/3/incidents",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "value": "00:01:51.213906"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/api/query/incidents?%24limit=30",
        "@type": "hydra:PartialCollectionView"
    }
}

Associations

Wherever a "field" key is specified in a query object, you can use dot-notation to query against an associated entity using the same operators that are available for the root record.

Example

Query all records assigned to a user named Jeff.

{
  "logic": "AND",
  "filters": [
    {
      "field": "assignedToUser.firstname",
      "operator": "eq",
      "value": "Jeff"
    }
  ]
}

Model Type

Use this API to search for records from different models like Incident, Alerts or any other custom models based on multiple valid fields in the model.

The API is: https://{{hostname}}/api/query/{{modelType}}. For example, https://{{hostname}}/api/query/incidents where incidents is a model in which you want to search for records. This API uses POST as the request method.

Example

BODY: 
{
    "aggregates": [
        {
            "operator": "groupby",
            "field": "phase.itemValue",
            "alias": "phase"
        },
        {
            "operator": "avg",
            "field": "dwellTime",
            "alias": "maxDwellTime"
        }
    ],
    "logic": "AND",
    "filters": []
}

Response: JSON list of records matching the filter criteria provided in the BODY of the modelType.

Get only specified fields in the API response body while querying a module

Use the "__selectFields" parameter in the request body of 'query' APIs such as /api/query/alerts, to get only the fields you have specified in the API response body when you exporting or fetching alert records using the API.

Example

__selectFields: ["id", "severity"]

Response: The API response body will contain only the "id" and "severity" fields when you exporting or fetching alert records using the API.

Ignore specified fields from the API response body while querying a module

Use the "__ignoreFields" parameter in the request body of 'query' APIs such as /api/query/alerts, to ignore the fields you have specified from the API response body when you exporting or fetching alert records using the API.

Example

__ignoreFields: ["createDate", "createUser"]

Response: The API response body of the exported alert records will contain all fields except the "createDate" and "createUser" fields.