{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Use Case: Retrieving record data","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":"use-case-retrieving-record-data","__idx":0},"children":["Use Case: Retrieving record data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you understand ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/process-intelligence-apis/knowledge-model-api/tutorials/learning/exploring-schema"},"children":["how the schema endpoints work"]},", you are ready to start getting data for the"," ","records."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"data-endpoint","__idx":1},"children":["Data endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order to get data for a record, you need to start building the URL for the Knowledge Model and record you want to"," ","consume. This URL should follow this pattern:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://<team>.<cluster>.celonis.cloud/intelligence/api/knowledge-models/<km_id>/records/<record_id>/data"]}," where:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<team>"]}," is the name for your team in the EMS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<cluster>"]}," the cluster assigned for you (i.e. us-2, eu-3, etc.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<km_id>"]}," the id for the Knowledge Model you want to query. You can get it through the schema endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<record_id>"]}," id for the record. You can get this through the schema endpoints."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"specifying-the-fields-that-you-want-to-consume","__idx":2},"children":["Specifying the fields that you want to consume"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The above URL won't do much on its own. You need to specify the list of fields that you want to consume."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call fields to one of the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Augmented Attributes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Flags"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order to specify which fields you want to get data for, you need to pass a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," query parameter and specify the"," ","list of field ids that you previously got from the record schema endpoint separated by commas. For example, if you want to get"," ","the data for three fields called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVITIES"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EVENTTIME"]},", then you need to specify the query parameter in the following way:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields: ID, ACTIVITIES, EVENTTIME"]},". Keep in mind that the ids are case sensitive. In Postman, this should look like this:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/fields-parameter.6964b7f4a2b5a8139d12d82b1eb4b3b98e8ce4d6172c6eb7f376b44289d581f3.3c53a942.png","alt":"Fields parameter"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the information is correct, you should get a response like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"page\": 0,\n  \"pageSize\": 50,\n  \"total\": 2,\n  \"sort\": [],\n  \"content\": {\n    \"headers\": [\n      {\n        \"id\": \"ID\",\n        \"name\": \"Id\",\n        \"type\": \"integer\",\n        \"format\": \",.0f\",\n        \"aggregation\": false,\n        \"filterable\": true,\n        \"sortable\": true\n      },\n      {\n        \"id\": \"EVENTTIME\",\n        \"name\": \"Eventtime\",\n        \"type\": \"date\",\n        \"format\": \"%Y-%m-%d\",\n        \"aggregation\": false,\n        \"filterable\": true,\n        \"sortable\": true\n      },\n      {\n        \"id\": \"ACTIVITIES\",\n        \"name\": \"Activities\",\n        \"type\": \"string\",\n        \"aggregation\": false,\n        \"filterable\": true,\n        \"sortable\": true\n      }\n    ],\n    \"data\": [\n      {\n        \"EVENTTIME\": \"2015-05-01\",\n        \"ACTIVITIES\": \"Put in the oven\",\n        \"ID\": 1\n      },\n      {\n        \"EVENTTIME\": \"2015-05-01\",\n        \"ACTIVITIES\": \"Roll out the dough\",\n        \"ID\": 0\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's analyze the response:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},": As you have probably noticed for other endpoints, most of the information that the Knowledge Model API returns is"," ","paginated. You can navigate through the different pages, changing the value of this parameter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},": Lets you specify the size of the page with the results. The default value is 50."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]},": Tells you total number of entries that are being returned by your query to the data endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort"]},": As you will see in following sections, you can sort the returned information. This parameter will show you which"," ","sort criteria is being used."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]},": Contains the data for the record that is being requested",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["header"]},": If you consider the data returned as a table, then the list of fields that you are passing will be the headers."," ","This attribute will also tell you the format that this field has and other information like for example if it's filterable"," ","or sortable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},": Contains the actual data that corresponds to each of the header/fields that were specified."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So, for the example above, you got two rows of data. The first one corresponds with the activity \"Put in the oven\" that has"," ","an id equal to 1 and happened on 2015-05-01. According to the headers you should be able to filter and sort by any of"," ","the headers (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVITIES"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EVENTTIME"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sorting-the-data-in-your-sample-response","__idx":3},"children":["Sorting the data in your sample response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this example, you can see that the activities are not correctly ordered. You would like to have \"Roll out the dough\""," ","first and then \"Put in the oven\" second. To achieve this, you can sort the data by the ID."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the data endpoint, you can specify a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort"]}," query parameter with the fields that you would like to use for sorting."," ","These fields need to be separated by a comma. You can also specify if you want that field to be sorted ascending or"," ","descending. If you want the field to be sorted ascending you need to prepend a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]}," character to the name of the field,"," ","whereas if you want the field to be sorted descending you will need to prepend a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-"]}," character. For example:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort: +id, -Activities"]}," will sort the data first by id ascending and then it will sort it by the activity names in a"," ","descending way."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example you wanted to sort by id, so you can just specify the following query parameter ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort: id"]},"."," ","Notice that the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]}," character is optional, as it is the default criteria if no criteria is specified."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"filtering-the-data-in-this-example","__idx":4},"children":["Filtering the data in this example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now, let's imagine you have hundreds or thousands of rows being returned by your query. How can you filter the entries that"," ","you are interested in?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using one or more Knowledge Model filter/s."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Specifying a filter expression in the request."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-to-use-knowledge-model-filters","__idx":5},"children":["How to use Knowledge Model filters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your Knowledge Model may already contain some filters. These filters can be retrieved by the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getFilters/"},"children":["filters schema endpoint"]},". For example, you could"," ","have a filter with an id \"roll_out_the_dough\" that filters all the entries that have an activity with the name"," ","\"Roll out the dough\"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you wanted to use this filter in your query, you can simply pass it in the query parameter ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters"]},". In your example,"," ","you can filter only the \"Roll out the dough\" entries with the query parameter ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters: roll_out_the_dough"]},". Similar to"," ","the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort"]},", you can specify more than one filter by separating the ids by a comma."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-to-specify-a-filter-expression-in-the-request","__idx":6},"children":["How to specify a filter expression in the request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you wanted to filter the entries that contain an activity called \"Roll out the dough\", you could also specify a filter"," ","expression in your request. The filter expressions follow the 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 the id of the field that you want to filter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operator"]},": is one of the following operators ",{"$$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 like 'Roll out the dough'."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So, in your example, you could achieve the same result as using a Knowledge Model filter by specifying the following query parameter:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr: ACTIVITIES eq 'Roll out the dough'"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also possible to combine filters with logical operators, parenthesis and some OData predictors:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["and, or, not"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startswith, endswith, contains"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These predictors have the following structure:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["predictor"]}," is an OData predicator's name"]},{"$$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":["value"]}," is a constant, such as a Salesforce Opportunity ID or a text."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, another way to achieve the same result is by using a predictor specifying the following query parameter:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr: startswith(ACTIVITIES,'Roll out the dough')"]},". You can specify multiple filter expressions, simply separating them by a comma or combining them with logical operators."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hopefully, with this information, you should now be able to get, sort and filter all the record data that you need. If"," ","you got this far, we would like to hear from you. Have you found any limitation or something tha you would like us to"," ","improve? If so, please fill our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.google.com/forms/d/e/1FAIpQLSeHANiDNRaHNCbdgH0hc1kQv35V2yHb5gkDpZTYjoT-6Gd-rQ/viewform?usp=sf_link"},"children":["feedback form"]}," ","that will help us to improve our API."]}]},"headings":[{"value":"Use Case: Retrieving record data","id":"use-case-retrieving-record-data","depth":1},{"value":"Data endpoint","id":"data-endpoint","depth":2},{"value":"Specifying the fields that you want to consume","id":"specifying-the-fields-that-you-want-to-consume","depth":2},{"value":"Sorting the data in your sample response","id":"sorting-the-data-in-your-sample-response","depth":2},{"value":"Filtering the data in this example","id":"filtering-the-data-in-this-example","depth":2},{"value":"How to use Knowledge Model filters","id":"how-to-use-knowledge-model-filters","depth":3},{"value":"How to specify a filter expression in the request","id":"how-to-specify-a-filter-expression-in-the-request","depth":3}],"frontmatter":{"seo":{"title":"Use Case: Retrieving record data"}},"lastModified":"2026-05-20T14:52:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/process-intelligence-apis/knowledge-model-api/tutorials/learning/retrieve-record-data","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}