{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Filtering the records in a response","description":"API documentation for Celonis APIs.","siteUrl":"https://developer.celonis.com/","keywords":"celonis developer portal, celonis apis, celonis api reference docs","lang":"en-US","llmstxt":{"hide":false,"description":"Celonis API documentation","sections":[{"title":"API Docs","description":"Available Celonis API Docs","includeFiles":["**/*.md"],"excludeFiles":[]},{"title":"API Specs","description":"All Celonis API specifications","includeFiles":["**/openapi.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"filtering-the-records-in-a-response","__idx":0},"children":["Filtering the records in a response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Filtering allows API consumers to only retrieve the desired records and not the whole data set. There are two ways to filter the data returned by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/data"]}," endpoint."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"predefined-knowledge-model-filters","__idx":1},"children":["Predefined Knowledge Model filters"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply filters pre-defined in the Knowledge Model by using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]}," query parameter. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Filters:"]}," A comma-separated list of filter ids.  ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Note that:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Celonis Platform Knowledge Model allows filters to be defined using the FILTER PQL operator as explained in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.celonis.com/en/knowledge-model---filters.html"},"children":["Celonis Platform documentation"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can apply multiple filters by providing multiple filter ids separated by commas or use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]}," parameter multiple times."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Remember this parameter is case sensitive. The filter ids must match the one returned by the filter schema endpoint (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/knowledge-models/{km_id}/filters"]},")."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"filters=not_null_orders,delayed_orders or filters=not_null_orders&filters=delayed_orders\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ad-hoc-filter-expressions","__idx":2},"children":["Ad-hoc filter expressions"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Filter expression using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr"]}," query parameter.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"This parameter allows filtering of record data using a provided value of a field through an expression."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"legacy-filter-expressions","__idx":3},"children":["Legacy filter expressions"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["First pattern ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field operator value"]}," where:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field"]}," is a filterable attribute, augmented attribute or flag of a record. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This value is case-sensitive and should be equal to the attribute id."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operator"]}," is a comparison operator. For this pattern, it is currently supported by following operators:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eq(=), gt(>), lt(<), ne(!=), ge(>=), le(<=), is(IS) and in(IN)"]}]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is a constant, such as a Salesforce Opportunity ID or a number/text."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Second pattern ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operator(field,value)"]}," where:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operator"]}," is a string search operator,similar to the LIKE in the SQL clause. For this pattern, it is currently supported by following operators:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startswith, endswith and contains"]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also possible to combine filters with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["logical operators ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["and, or, not"]}," and parenthesis"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of the first pattern"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"filterExpr=field1 eq value,field2 ne value\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of the second pattern"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"filterExpr=startswith(field1,value),contains(field2,value)\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example with first pattern, second pattern and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["or"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"filterExpr=startswith(field1,value) or filed3 eq value,contains(field2,value) or field3 eq value\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"filterExpr=not startswith(field1,value) or filed3 eq value,not (contains(field2,value) or field3 eq value)\n"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n    \"page\": 0,\n    \"pageSize\": 100,\n    \"total\": 1,\n    \"sort\": [],\n    \"content\": {\n        \"headers\": [\n            {\n                \"id\": \"description\",\n                \"name\": \"Description\",\n                \"type\": \"string\",\n                \"aggregation\": false,\n        ===>    \"filterable\": true,  \n                \"sortable\": true\n            }\n            {\n                \"id\": \"count\",\n                \"name\": \"Count\",\n                \"type\": \"integer\",\n                \"aggregation\": true,\n        ===>    \"filterable\": false,\n                \"sortable\": true\n            }\n        ],\n        \"data\": [\n            {\n                \"description\": \"total\"\n                \"count\": 50\n            }\n        ]\n    }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can apply multiple filters separated by commas or use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr"]}," parameter multiple times separated by “&”."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr=opportunity_id eq AA00022475H, opportunity_value gt 50000"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"filterExpr=opportunity_id eq AA00022475H& \nfilterExpr=opportunity_value gt 50000\n"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr"]}," value contains special characters such as spaces, quotes, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["("]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[")"]},", make sure to URL-encode only the query parameter value (not the full URL) before sending the request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]}," is used to separate query parameters, an unencoded ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]}," inside the filter expression will be interpreted as a parameter separator and break the request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/process-intelligence-apis/knowledge-model-api/features/url-encoding"},"children":["URL Encoding of Query Parameters"]}," for examples."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"differences-between-legacy-and-filter-expression-syntax","__idx":4},"children":["Differences between legacy and filter expression syntax"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information on the filter expression syntax, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/process-intelligence-apis/knowledge-model-api/features/filtering-odata-typed"},"children":["Using filter expressions with OData semantics"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OData Syntax"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Legacy Syntax"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String values should be single quoted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["''"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String values can be unquoted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date values should be in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ISO-8601"]}," format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date formatting follows ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.celonis.com/en/using-the-pql-editor.html#UUID-0a810432-93c4-d090-4e7b-9194784fe28e_section-idm234427867703289"},"children":["Celonis date format semantics"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only logical operators ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["and"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["or"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Comma (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[","]},") can be used instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["and"]}," operator"]}]}]}]}]}]},"headings":[{"value":"Filtering the records in a response","id":"filtering-the-records-in-a-response","depth":1},{"value":"Predefined Knowledge Model filters","id":"predefined-knowledge-model-filters","depth":2},{"value":"Ad-hoc filter expressions","id":"ad-hoc-filter-expressions","depth":2},{"value":"Legacy filter expressions","id":"legacy-filter-expressions","depth":3},{"value":"Differences between legacy and filter expression syntax","id":"differences-between-legacy-and-filter-expression-syntax","depth":3}],"frontmatter":{"seo":{"title":"Filtering the records in a response"}},"lastModified":"2026-05-20T14:52:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/process-intelligence-apis/knowledge-model-api/features/filtering","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}