diff --git a/shared/KieServer/JavaClientAPI-section.adoc b/shared/KieServer/JavaClientAPI-section.adoc
index 56d7a8930e..ed12e84521 100644
--- a/shared/KieServer/JavaClientAPI-section.adoc
+++ b/shared/KieServer/JavaClientAPI-section.adoc
@@ -137,6 +137,28 @@ public void listContainers() {
 }
 ----
 
+It is also possible to list the containers based on specific ReleaseId (and its individual parts) or status:
+
+.Listing Kie Containers with custom filter
+[example]
+
+[source,java]
+----
+public void listContainersWithFilter() {
+    // the following filter will match only containers with ReleaseId "org.example:contatner:1.0.0.Final" and status FAILED
+    KieContainerResourceFilter filter = new KieContainerResourceFilter.Builder()
+            .releaseId("org.example", "container", "1.0.0.Final")
+            .status(KieContainerStatus.FAILED)
+            .build();
+    KieContainerResourceList containersList = kieServicesClient.listContainers(filter).getResult();
+    List<KieContainerResource> kieContainers = containersList.getContainers();
+    System.out.println("Available containers: ");
+    for (KieContainerResource container : kieContainers) {
+        System.out.println("\t" + container.getContainerId() + " (" + container.getReleaseId() + ")");
+    }
+}
+----
+
 == Managing Containers
 
 
diff --git a/shared/KieServer/RestAPI-section.adoc b/shared/KieServer/RestAPI-section.adoc
index 1738ab6977..f5184564a2 100644
--- a/shared/KieServer/RestAPI-section.adoc
+++ b/shared/KieServer/RestAPI-section.adoc
@@ -51,7 +51,6 @@ The commands itself can be found in the `org.kie.server.api.commands` package.
 
 == [GET] /containers
 
-
 Returns a list of containers that have been created on this Execution Server.
 
 .Example Server Response
@@ -77,6 +76,13 @@ Returns a list of containers that have been created on this Execution Server.
 ----
 ====
 
+The endpoint supports also filtering based on `ReleaseId` and `container status`. Examples:
+
+* `/containers?groupId=org.example` - returns only containers with the specified groupId
+* `/containers?groupId=org.example&artifactId=project1&version=1.0.0.Final` - returns only containers with the specified `ReleaseId`
+* `/containers?status=started,failed` - returns containers which are either started or failed
+
+
 == ⁠[GET] /containers/{id}