> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DEE responses

> Reference for the JSON response format of DEE REST endpoints, covering the common `Response` object with `status` and `entity` fields, error responses, and endpoint specific results such as task IDs, task status DTOs, and Enhanced Drillthrough results.

## Common JSON format across all the results

All the results returned by the REST API are nested within the `Response` object's `entity` field as follows:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": "http status code: 200, 400, 500, ...",
  "entity": {
    ...
  }
}
```

<Note>
  All responses are contained within a `Response` object. The `entity` field contains the actual response data. The `status` field contains the HTTP status code of the response. The responses may contain additional data from the `Response` object.
</Note>

In case of an error, the following structure is sent (the `Response`'s status field is set to `500`):

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 500,
  "entity": {
    "errorChain": [
      {
        "type": "",
        "message": ""
      },
      ...
    ],
    "stackTrace": ""
  }
}
```

## Endpoints and responses

The following matrix outlines the different endpoints and the information their response contains.

| Endpoint                                                                          | Response                                                                           |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [submitOrders](/user-guide/responses/overview#submit-calls)                       | Returns the list of task ids (String) as a result.                                 |
| [submitTemplateOrders](/user-guide/responses/overview#submit-calls)               | Returns the list of task ids (String) as a result.                                 |
| [addTemplateOrder](/user-guide/responses/overview#template-calls)                 | Does not return any specific value                                                 |
| [removeTemplateOrder](/user-guide/responses/overview#template-calls)              | Does not return any specific value                                                 |
| [clearOldCompletedTasks](/user-guide/responses/overview#clean-up-calls)           | Returns the number of tasks cleared                                                |
| [isTaskCompleted](/user-guide/responses/overview#check-if-tasks-is-completed)     | Simply returns a boolean.                                                          |
| [isTaskListCompleted](/user-guide/responses/overview#check-if-tasks-is-completed) | Simply returns a boolean.                                                          |
| [getTaskStatus](/user-guide/responses/overview#status-calls)                      | Returns a result based on the `DeeTaskInfoDTO` and `DeeResultFileInfoDTO` classes. |
| [getTaskListStatus](/user-guide/responses/overview#status-calls)                  | Returns a result based on the `DeeTaskInfoDTO` and `DeeResultFileInfoDTO` classes. |
| [cancelTask](/user-guide/responses/overview#status-calls)                         | Returns a result based on the `DeeTaskInfoDTO` and `DeeResultFileInfoDTO` classes. |
| [cancelTaskList](/user-guide/responses/overview#status-calls)                     | Returns a result based on the `DeeTaskInfoDTO` and `DeeResultFileInfoDTO` classes. |

### Enhanced Drillthrough endpoints and responses

Here are the endpoints exposed by the Enhanced Drillthrough component of the Extraction Engine:

| Endpoint                                                                                                      | Response                                                                                                        |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [executeSearchFacts](/user-guide/responses/overview#execute-search-facts-query)                               | Returns a list of Object\[] representing the extracted attributes for each fact that fell into the query scope. |
| [executeEnhancedDrillthrough](/user-guide/responses/overview#execute-enhanced-drillthrough-query)             | Returns no content, just an ok or error status                                                                  |
| [retrieveEnhancedDrillthroughResult](/user-guide/responses/overview#retrieve-enhanced-drillthrough-result)    | Returns the current status of the task in an EnhancedDrillthroughTaskInfoDTO object.                            |
| [cancelEnhancedDrillthrough](/user-guide/responses/overview#cancel-enhanced-drillthrough)                     | Returns the last status of the task if the query has been cancelled, nothing otherwise                          |
| [getEnhancedDrillthroughMaxRows/{pivotId}](/user-guide/responses/overview#get-enhanced-drillthrough-max-rows) | Returns the max rows value for the specified cube                                                               |
| [executeEnhancedCount](/user-guide/responses/overview#execute-enhanced-count)                                 | Returns the number of aggregate DTOs returned as results of the query.                                          |

## Response examples

Below are examples for the different endpoints.

### Submit calls

The methods `submitOrders` and `submitTemplateOrders` return the list of task ids (String) as a result.

**Example response for `submitOrders`:**

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": [
    "1612394532198_2"
  ]
}
```

### Template calls

The methods `addTemplateOrder` and `removeTemplateOrder` do not return any specific value.

### Clean-up calls

The method `clearOldCompletedTasks` returns the number of tasks cleared.

**Example response:**

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": 1
}
```

### Check if task(s) is completed

The methods `isTaskCompleted` and `isTaskListCompleted` simply return a boolean.

**Example response for `isTaskCompleted`:**

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": true
}
```

### Status calls

The methods `getTaskStatus`, `getTaskListStatus`, `cancelTask` and `cancelTaskList` return a result based on the `DeeTaskInfoDTO` and `DeeResultFileInfoDTO` classes.

<Info>
  Below are examples of JSON response DTO objects:
</Info>

### JSON status call result format

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": {
    "taskId": "1",
    "taskOwner": "admin",
    "taskStatus": "RUNNING",
    "statusLastUpdateTime": "24/01/2020 12:58:23",
    "orderName": "orderName",
    "orderDescription": "orderDesc",
    "taskCreationTime": "24/01/2020 12:58:23",
    "taskRunStartTime": "24/01/2020 12:58:23",
    "taskRunStopTime": "24/01/2020 12:58:23",
    "taskExceptionMessage": "exceptionMessage",
    "taskExceptionDetails": "exceptionDetails",
    "dataSetDescription": "dataSetDesc",
    "dataRawSize": "2000",
    "resultFile": [
      {
        "url": "http://path/to/file",
        "size": 2000,
        "linesCount": 10
      }
    ]
  }
}
```

## Enhanced Drillthrough REST responses

### Execute search facts query

Returns a list of Object\[] representing the extracted attributes for each fact that fell into the query scope.

### Execute Enhanced Drillthrough query

Returns no content, just an ok or error status.

### Retrieve Enhanced Drillthrough result

The REST service returns a JSON object following the `EnhancedDrillthroughTaskInfoDTO` definition.

Example of output:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": {
    "taskOwner": "admin",
    "taskStatus": "SUCCESS",
    "dataRawSize": "2000",
    "taskException": "",
    "resultFiles": [
      {
        "url": "",
        "size": 2000,
        "linesCount": -1
      }
    ]
  }
}
```

### Cancel Enhanced Drillthrough

The REST service returns a JSON object following the `EnhancedDrillthroughTaskInfoDTO` definition.

Example of output:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": {
    "taskOwner": "admin",
    "taskStatus": "CANCELLED",
    "dataRawSize": "",
    "taskException": "",
    "resultFiles": []
  }
}
```

### Get Enhanced Drillthrough max rows

This returns the maximum number of rows the enhanced drill-through is allowed to extract for a specific cube.

Example of output:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": 10
}
```

### Execute Enhanced count

This retrieves the contributors.COUNT for a particular location, with some custom logic to ensure appropriate count calculation when dealing with analysis dimensions in the target cube.

Example of output:

```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
{
  "status": 200,
  "entity": 10
}
```