> ## 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.

# LISTEN_STATUS

> Reference for the `LISTEN_STATUS` DLC operation, covering the `DlcListenStatusRequest`, the `DlcListenStatusResponse`, and the `ListenReport` returned for a listener identified by `listenId`.

## Overview

This can retrieve the status of listeners that are currently open, or that have been closed.

The status of a listener can be retrieved through the listenId provided in the response of the
[`START_LISTEN`](/operations/operations-start-listen) operation.

## Request

<Tabs>
  <Tab title="Java">
    ### `DlcListenStatusRequest`

    | Key      | Required | Type     | Description                          |
    | -------- | :------: | :------- | ------------------------------------ |
    | listenId |     Y    | `String` | The unique identifier of a listener. |

    #### Example:

    ```Java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
    DlcListenStatusRequest.builder()
        .listenId("234890")
        .build();
    ```
  </Tab>

  <Tab title="JSON">
    ### `DlcListenStatusRequestDTO`

    | Key      | Required | Type     | Description                          |
    | -------- | :------: | :------- | ------------------------------------ |
    | listenId |     Y    | `String` | The unique identifier of a listener. |

    #### Example:

    ```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
    {
      "operation": "LISTEN_STATUS",
      "listenId": "234890"
    }
    ```
  </Tab>
</Tabs>

## Response

<Tabs>
  <Tab title="Java">
    ### `DlcListenStatusResponse`

    | Key    | Type              | Description                                                      |
    | ------ | :---------------- | ---------------------------------------------------------------- |
    | report | `ListenReport<E>` | Reports of all events that occurred while the listener was open. |
    | status | `DlcStatus`       | Overall status of the DLC Operation.                             |

    ### `ListenReport<E>`

    | Key       | Type            | Description                                                                                           |
    | --------- | :-------------- | ----------------------------------------------------------------------------------------------------- |
    | isOpen    | `boolean`       | Whether the listener is currently open or closed.                                                     |
    | startTime | `LocalDateTime` | The time and date the listener was started. Uses the JVM's time zone.                                 |
    | endTime   | `LocalDateTime` | The time and date the listener was closed. Uses the JVM's time zone. Will be null for open listeners. |
    | events    | `List<E>`       | List of events that occurred while the listener was open. The type of event depends on the source.    |
  </Tab>

  <Tab title="JSON">
    ### `DlcListenStatusResponseDTO`

    | Key       | Type                    | Description                                                                                           |
    | --------- | :---------------------- | ----------------------------------------------------------------------------------------------------- |
    | isOpen    | `boolean`               | Whether the listener is currently open or closed.                                                     |
    | startTime | `LocalDateTime`         | The time and date the listener was started. Uses the JVM's time zone.                                 |
    | endTime   | `LocalDateTime`         | The time and date the listener was closed. Uses the JVM's time zone. Will be null for open listeners. |
    | events    | `List<DlcLoadResponse>` | List of events that occurred while the listener was open. The type of event depends on the source.    |

    #### Example:

    ```json theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
    {
      "report": {
        "isOpen": true,
        "startTime": "2025-02-14T12:00:00",
        "endTime": null,
        "events": [
          {}
        ]
      },
      "status": "OK"
    }
    ```
  </Tab>
</Tabs>

### Expected event types

The type parameter of the `ListenReport` can vary depending on the type of source being listened on.

#### File sources: `ListenReport<DlcLoadResponse>`

When listening on a file source, the listen report will contain [`DlcLoadResponse`](/operations/operations-load#response) events as the listen operation
will perform many [`LOAD`](/operations/operations-load) operations.

### `DlcStatus`

A simple enum to capture if the DLC request was executed.

| Key   | Description                                     |
| ----- | ----------------------------------------------- |
| OK    | Request was handled successfully.               |
| ERROR | Request was not able to be performed correctly. |

### How it works

All listen operations are recorded and linked to a unique `listenId`. This ID can then be used to fetch the listener's
`ListenReport<DlcLoadResponse>`.