Add client APIs to list instance IDs and read orchestration history

client/src/main/java/com/microsoft/durabletask/DurableTaskClient.java

@@ -2,8 +2,11 @@
 // Licensed under the MIT License.
 package com.microsoft.durabletask;
 
+import com.microsoft.durabletask.history.HistoryEvent;
+
 import javax.annotation.Nullable;
 import java.time.Duration;
+import java.util.List;
 import java.util.concurrent.TimeoutException;
 
 /**
@@ -226,6 +229,39 @@ public abstract OrchestrationMetadata waitForInstanceCompletion(
      */
     public abstract OrchestrationStatusQueryResult queryInstances(OrchestrationStatusQuery query);
 
+    /**
+     * Lists the IDs of terminal orchestration instances that completed within a time window.
+     * <p>
+     * Unlike {@link #queryInstances(OrchestrationStatusQuery)}, which filters by creation time and returns full
+     * metadata, this method filters by <em>completion</em> time and returns only instance IDs, making it efficient
+     * for bulk enumeration such as archival/export. Results are paged; pass
+     * {@link ListInstanceIdsResult#getContinuationToken()} back via
+     * {@link ListInstanceIdsQuery#setContinuationToken(String)} to fetch subsequent pages.
+     *
+     * @param query filter criteria: completion-time window, terminal runtime statuses, page size, and pagination cursor
+     * @return a page of matching instance IDs and a cursor for the next page
+     * @throws UnsupportedOperationException if the current client implementation does not support listing instance IDs
+     */
+    public ListInstanceIdsResult listInstanceIds(ListInstanceIdsQuery query) {
+        throw new UnsupportedOperationException(
+                "Listing instance IDs is not supported by this client implementation.");
+    }
+
+    /**
+     * Gets the full history of an orchestration instance as an ordered list of {@link HistoryEvent} objects.
+     * <p>
+     * The events are returned in execution order. This is useful for archiving or offline analysis of an instance's
+     * execution history. Use {@code instanceof} to inspect each concrete event type.
+     *
+     * @param instanceId the unique ID of the orchestration instance whose history to fetch
+     * @return the instance's history events in order; empty if the instance has no history
+     * @throws UnsupportedOperationException if the current client implementation does not support history retrieval
+     */
+    public List<HistoryEvent> getOrchestrationHistory(String instanceId) {
+        throw new UnsupportedOperationException(
+                "Retrieving orchestration history is not supported by this client implementation.");
+    }
+
     /**
      * Initializes the target task hub data store.
      * <p>

client/src/main/java/com/microsoft/durabletask/DurableTaskGrpcClient.java

@@ -4,6 +4,8 @@
 
 import com.google.protobuf.StringValue;
 import com.google.protobuf.Timestamp;
+import com.microsoft.durabletask.history.HistoryEvent;
+import com.microsoft.durabletask.implementation.protobuf.OrchestratorService;
 import com.microsoft.durabletask.implementation.protobuf.OrchestratorService.*;
 import com.microsoft.durabletask.implementation.protobuf.TaskHubSidecarServiceGrpc;
 import com.microsoft.durabletask.implementation.protobuf.TaskHubSidecarServiceGrpc.*;
@@ -295,6 +297,37 @@ private OrchestrationStatusQueryResult toQueryResult(QueryInstancesResponse quer
         return new OrchestrationStatusQueryResult(metadataList, queryInstancesResponse.getContinuationToken().getValue());
     }
 
+    @Override
+    public ListInstanceIdsResult listInstanceIds(ListInstanceIdsQuery query) {
+        Helpers.throwIfArgumentNull(query, "query");
+        ListInstanceIdsRequest.Builder builder = ListInstanceIdsRequest.newBuilder();
+        Optional.ofNullable(query.getCompletedTimeFrom()).ifPresent(from -> builder.setCompletedTimeFrom(DataConverter.getTimestampFromInstant(from)));
+        Optional.ofNullable(query.getCompletedTimeTo()).ifPresent(to -> builder.setCompletedTimeTo(DataConverter.getTimestampFromInstant(to)));
+        String requestContinuationToken = query.getContinuationToken() != null ? query.getContinuationToken() : "";
+        builder.setLastInstanceKey(StringValue.of(requestContinuationToken));
+        builder.setPageSize(query.getPageSize());
+        query.getRuntimeStatusList().forEach(runtimeStatus -> Optional.ofNullable(runtimeStatus).ifPresent(status -> builder.addRuntimeStatus(OrchestrationRuntimeStatus.toProtobuf(status))));
+        ListInstanceIdsResponse response = this.sidecarClient.listInstanceIds(builder.build());
+        String continuationToken = response.hasLastInstanceKey() ? response.getLastInstanceKey().getValue() : null;
+        return new ListInstanceIdsResult(new ArrayList<>(response.getInstanceIdsList()), continuationToken);
+    }
+
+    @Override
+    public List<HistoryEvent> getOrchestrationHistory(String instanceId) {
+        Helpers.throwIfArgumentNull(instanceId, "instanceId");
+        StreamInstanceHistoryRequest request = StreamInstanceHistoryRequest.newBuilder()
+                .setInstanceId(instanceId)
+                .build();
+        List<HistoryEvent> historyEvents = new ArrayList<>();
+        Iterator<HistoryChunk> chunks = this.sidecarClient.streamInstanceHistory(request);
+        while (chunks.hasNext()) {
+            for (OrchestratorService.HistoryEvent protoEvent : chunks.next().getEventsList()) {
+                historyEvents.add(HistoryEventConverter.fromProto(protoEvent));
+            }
+        }
+        return historyEvents;
+    }
+
     @Override
     public void createTaskHub(boolean recreateIfExists) {
         this.sidecarClient.createTaskHub(CreateTaskHubRequest.newBuilder().setRecreateIfExists(recreateIfExists).build());

client/src/main/java/com/microsoft/durabletask/EntityQueryPageable.java

@@ -17,7 +17,7 @@
  * <p>
  * Use {@link DurableEntityClient#getAllEntities(EntityQuery)} to obtain an instance of this class.
  *
- * <h3>Example: iterate over all entities</h3>
+ * <h2>Example: iterate over all entities</h2>
  * <pre>{@code
  * EntityQuery query = new EntityQuery()
  *     .setInstanceIdStartsWith("counter")
@@ -28,7 +28,7 @@
  * }
  * }</pre>
  *
- * <h3>Example: iterate page by page</h3>
+ * <h2>Example: iterate page by page</h2>
  * <pre>{@code
  * for (EntityQueryResult page : client.getEntities().getAllEntities(query).byPage()) {
  *     System.out.println("Got " + page.getEntities().size() + " entities");